SPFx 자동 호스팅: .sppkg 하나로 배포가 끝나는 이유

들어가며

SPFx 솔루션을 배포할 때 "코드를 어디에 올려야 하나"를 고민해 본 적이 있다면, 그 고민 자체가 이미 오래된 것입니다. 지금은 .sppkg 파일 하나만 앱 카탈로그에 올리면 JavaScript, CSS, 이미지가 전부 테넌트 안에서 자동으로 서빙됩니다. 개발자가 외부 웹사이트나 스토리지 계정을 준비할 필요가 없습니다.

이 글은 그 기능이 무엇을 대신해 주고, 무엇은 대신해 주지 않는지를 정리합니다. 특히 "자동 호스팅과 CDN 중에 뭘 써야 하나"라는 질문은 애초에 성립하지 않는다는 점을 먼저 짚고, 실제 확인 명령까지 다룹니다.

핵심 개념

SPFx 의 "자동 호스팅(automatic hosting)" 은 빌드 산출물(JS, CSS, 이미지)을 .sppkg 안에 넣어 두면, 테넌트 앱 카탈로그에 배포하는 순간 SharePoint 가 그 파일들을 테넌트 내부 라이브러리로 풀어내고, 페이지는 그 안에서 코드를 불러오게 해 주는 기능입니다. 개발자나 고객이 별도 웹사이트를 준비할 필요가 없습니다.

왜 생겼나 (SPFx 1.4, 2017년 12월 이전 상황)

그 전에는 코드를 어딘가에서 HTTP(S) 로 서빙해야 했습니다. 보통 Azure Storage 나 웹앱에 CDN 을 세우고 여기에 번들을 올렸습니다. 그러면 다음과 같은 부담이 따라왔습니다.

• 외부 사이트 개설과 유지보수, 비용, 그에 따른 IT 조직 승인 절차
• "우리 테넌트 밖의 애플리케이션이 우리 데이터를 본다"는 보안 검토 이슈
• 코드를 고칠 때마다 외부 CDN 업로드를 잊지 않아야 하는 운영 리스크

자동 호스팅은 이 외부 사이트 자체를 없애자는 발상입니다.

자동 호스팅은 SPFx v1.4(2017년 12월 7일 릴리스)에서 도입됐습니다. 해당 릴리스 노트에는 "@microsoft/sp-build-web: 빌드 자산을 .sppkg 파일에 포함해 SharePoint 가 호스팅할 수 있도록 함"으로 기록되어 있고, 같은 날 Microsoft 365 Developer Blog 는 "JavaScript, CSS 및 기타 리소스가 통합 SharePoint CDN 에 자동 배포되어 별도의 CDN 과 패키지 배포 과정에 비해 단계가 크게 단순해졌다"고 설명했습니다. 지금은 신규 SPFx 솔루션의 기본값이고, SharePoint 뿐 아니라 Teams, Outlook, Viva, Microsoft 365 앱(Office) 전부에 동일하게 적용됩니다.

동작 원리 (실제 순서)

1. 빌드 시 ./config/package-solution.json 의 includeClientSideAssets 가 true 면 번들, 이미지, CSS 가 .sppkg(실은 zip) 안에 포함됩니다. 기본값이 true 입니다.
2. 관리자가 그 .sppkg 를 테넌트 앱 카탈로그에 업로드하고 배포합니다.
3. SharePoint 가 이를 감지해 자산을 앱 카탈로그 사이트 모음의 ClientSideAssets 라이브러리로 자동 추출합니다. 경로는 대략 https://<테넌트>.sharepoint.com/sites/apps/ClientSideAssets/ 형태입니다.
4. 컴포넌트가 실제 페이지에서 실행될 때, 매니페스트의 자산 URL 이 이 중앙 위치를 가리키도록 동적으로 치환됩니다. 개발자가 URL 을 하드코딩하는 게 아니라 테넌트가 런타임에 결정합니다.
5. 그래서 코드가 테넌트 안에서, 그 테넌트의 인프라 위에서 서빙됩니다.

자동 호스팅과 CDN 은 같은 것이 아니라 직교합니다

여기서 자주 오해가 생깁니다. 둘은 대체 관계가 아니라 서로 다른 층위입니다.

• 테넌트에 Microsoft 365 CDN 이 켜져 있으면, 그 ClientSideAssets 라이브러리를 CDN 이 오리진으로 삼아 publiccdn.sharepointonline.com 계열 URL 로 더 빠르게 서빙합니다.
• CDN 이 꺼져 있으면 같은 파일을 앱 카탈로그 사이트 모음에서 직접 서빙합니다.
• 어느 쪽이든 솔루션 패키지는 바꿀 필요가 없습니다. 테넌트 설정만 보고 SharePoint 가 알아서 결정합니다.

그래서 "자동 호스팅 = CDN" 도 아니고, "CDN 을 쓰려면 자동 호스팅을 꺼야 한다"도 아닙니다. 자동 호스팅은 자산을 어디에 두는가의 문제이고, CDN 은 그 자산을 누가 캐싱해서 내보내는가의 문제입니다.

Microsoft Learn 문서도 같은 내용을 확인해 줍니다. "Microsoft 365 CDN 이 활성화되어 있으면 기본 설정으로 자동 사용됩니다. 활성화되어 있지 않으면 자산은 앱 카탈로그 사이트 모음에서 서빙됩니다. 이 변경은 테넌트 설정에 따라 자동이며 실제 솔루션 패키지에는 아무런 변경이 필요하지 않습니다."

개발자가 건드리는 설정 3개

// ./config/package-solution.json
{
  "solution": {
    "includeClientSideAssets": true   // 자산을 sppkg 에 포함 → 자동 호스팅 (기본값)
  }
}

// ./config/write-manifests.json
{
  "cdnBasePath": ""   // 자동 호스팅을 쓸 때는 비워 둡니다.
}                     // 여기에 외부 CDN 경로가 들어 있으면 자동 호스팅이 동작하지 않습니다.

// ./config/package-solution.json (테넌트 전역 배포)
{
  "solution": {
    "skipFeatureDeployment": true   // 카탈로그 배포만으로 모든 사이트에 즉시 사용 가능
  }
}

skipFeatureDeployment: true 로 배포하면 관리자에게 "Enable this app and add it to all sites" 옵션이 주어지고, 체크하면 웹파트가 모든 사이트의 웹파트 선택기에 바로 나타납니다. 사이트별로 앱을 설치하는 단계가 사라집니다.

호스팅 옵션 3가지 비교

옵션	자산 위치	외부 사이트 필요	코드 수정 시
자동 호스팅(기본)	.sppkg → 테넌트 내 ClientSideAssets	없음	sppkg 재배포만
Microsoft 365 CDN 사용	같은 라이브러리를 CDN 이 서빙	없음(테넌트 내)	sppkg 재배포만
Azure CDN / 외부 호스팅	Azure Storage 등	필요	sppkg 재배포 + CDN 업로드 별도

즉 세 번째만 "두 곳을 따로 갱신"하는 구조이고, 앞의 두 개는 카탈로그 한 곳만 갱신하면 됩니다.

이 기능이 해 주지 않는 것 (오해 주의)

• 권한 처리는 안 해 줍니다. 컴포넌트는 여전히 페이지 안에서 사용자 ID 로 실행되고, 자동 SSO 로 사용자 권한 그대로 API 를 호출합니다. 자동 호스팅은 "코드 파일을 어디서 받아오나"만 해결합니다.
• Graph 나 Azure 자산 호출과는 무관합니다. 그건 별개로 잘 동작하며, 이 설정이 제약을 주지 않습니다.
• 게스트 사용자 이슈: 기본적으로 게스트는 ClientSideAssets 라이브러리에 읽기 권한이 없습니다. CDN 을 켜면 게스트도 접근 가능한 CDN URL 로 서빙되어 해결됩니다. PnP 문서도 "게스트는 기본적으로 이 라이브러리에 읽기 권한이 없다"고 명시하면서, 관리자가 라이브러리 권한을 직접 수정하는 방법도 대안으로 제시합니다. 다만 이게 실무에서 CDN 을 켜는 실질적 이유 중 하나인 것은 분명합니다.
• 라이브러리 내용을 직접 손으로 관리하는 건 앱 카탈로그 사이트 모음 관리자만 가능하고, 일반 사용자는 읽기만 합니다. 자산의 원본은 항상 .sppkg 입니다.
• 온프레미스는 별개 문제입니다. 자동 호스팅은 Microsoft 365(SharePoint Online) 기준입니다. SharePoint Server 2016/2019 같은 온프레미스에서는 호스팅 위치를 따로 결정해야 합니다. Learn 문서는 SPFx 1.4 가 SharePoint 2016 Feature Pack 2 와 호환되지 않는다고 밝히고 있습니다.

직접 확인하는 방법 (테넌트에서 확인)

문서만 보고 판단하지 말고 테넌트 상태를 직접 확인하는 편이 빠릅니다. 관리자 권한이 있는 계정으로 SharePoint Online Management Shell 또는 CLI for Microsoft 365 를 씁니다.

# SharePoint Online Management Shell
Connect-SPOService -Url https://contoso-admin.sharepoint.com
Get-SPOTenantCdnEnabled -CdnType Public
Get-SPOTenantCdnOrigins -CdnType Public

# CLI for Microsoft 365 (크로스 플랫폼)
m365 spo cdn get --type Public
m365 spo cdn origin list --type Public

여기까지 실행했을 때 공개 오리진 목록에 */clientsideassets 가 보이면 CDN 경로가 정상입니다.

없다면 문제가 됩니다. 이 오리진은 2017년 12월에 추가된 기본 오리진이고, 빠져 있으면 SPFx 솔루션이 경고나 오류 메시지 없이 실패합니다. Learn 문서가 명시하는 조용한 실패라서 원인을 찾기 어렵습니다. 이때는 오리진을 직접 추가합니다.

Add-SPOTenantCdnOrigin -CdnType Public -OriginUrl */CLIENTSIDEASSETS

m365 spo cdn origin add --origin */CLIENTSIDEASSETS

브라우저에서 확인하는 방법도 있습니다. 페이지를 열고 개발자 도구의 Network 탭에서 웹파트 번들이 어느 도메인에서 오는지 봅니다. publiccdn.sharepointonline.com 계열이면 CDN 경로이고, <테넌트>.sharepoint.com/sites/apps/ClientSideAssets/ 면 앱 카탈로그 직접 서빙입니다. 어느 쪽이든 정상입니다.

업데이트 흐름

번들을 고치면 프로덕션 빌드로 다시 패키징해 sppkg 를 카탈로그에 재배포합니다.

# SPFx 1.22 이상 (Heft 빌드툴)
heft build --production

# SPFx 1.21 이하 (구 gulp 계열)
gulp bundle --ship
gulp package-solution --ship

중앙 배포(tenant-wide)된 솔루션은 사이트별 업그레이드 작업이 없고, 모든 기존 인스턴스가 새 자산을 자동 참조합니다. 다만 브라우저와 CDN 캐싱이 있으므로 패키지 버전을 올려서 확실히 갱신되게 하는 게 안전합니다.

실무 판단 기준

• 대부분은 기본값 그대로 두고 테넌트에 Microsoft 365 CDN 만 켜면 끝입니다. 성능과 게스트 접근이 같이 해결됩니다.
• 외부 CDN(Azure)이 꼭 필요한 경우는 테넌트 CDN 으로 감당이 안 되는 트래픽이나 지역 분산 등 특수한 상황이고, 이때만 운영 부담이 두 배가 됩니다.
• 발표자가 "M365 에서 SPFx 만의 고유 기능"이라고 강조한 지점이 정확히 이것입니다. 테넌트 밖으로 나가는 의존을 만들지 않고 코드를 배포할 수 있는 모델입니다.

마무리

자동 호스팅을 한 문장으로 줄이면 이렇습니다. 자산은 패키지에 넣고, 배포는 카탈로그 한 곳에서 끝냅니다.

• includeClientSideAssets: true 가 기본값이고, cdnBasePath 는 비워 둡니다.
• CDN 은 자동 호스팅을 대체하지 않습니다. 테넌트 설정만 보고 SharePoint 가 서빙 경로를 정합니다.
• CDN 을 켰다면 오리진 목록에 */clientsideassets 가 있는지 확인합니다. 없으면 조용히 실패합니다.
• 권한과 SSO 는 이 기능의 범위가 아닙니다. 그건 사용자 컨텍스트에서 그대로 동작합니다.

확장 팁을 하나 덧붙이면, 새 솔루션을 카탈로그에 올릴 때마다 개발자 도구 Network 탭에서 번들 도메인을 한 번 확인하는 습관을 들이면 서빙 경로 문제를 배포 직후에 잡을 수 있습니다.

참고한 자료

• Microsoft Learn, SPFx 웹파트를 Microsoft 365 CDN 에서 호스팅 (Hello World part 4)
• Microsoft Learn, SharePoint Framework v1.4.0 릴리스 노트 (2017년 12월 7일)
• Microsoft Learn, SharePoint Online 에서 Microsoft 365 CDN 사용
• Microsoft Learn, SharePoint Online 의 CSP(Content Security Policy) 지원
• PnP 커뮤니티 블로그, Automatic hosting of SPFx code in Microsoft 365
• Microsoft 365 Developer Blog, SharePoint Framework 1.4 and new site updates now available (2017년 12월 7일)