정답부터 말하면, 대부분의 팀은 Wrangler 설정의 assets 폴더를 먼저 연결하고, 직접 업로드 API는 배포 시스템을 직접 만드는 경우에만 검토하면 됩니다. Cloudflare Workers Static Assets는 정적 파일 호스팅과 Worker 로직을 한 단위로 묶어 배포하는 방식이라, 랜딩페이지·문서 사이트·간단한 SaaS 대시보드의 앞단을 빠르게 올릴 때 유용합니다. 이 글은 처음 설정하는 실무자가 어디서부터 확인해야 하는지, 어떤 파일 구조가 편한지, 직접 업로드가 필요한 경우와 아닌 경우를 구분해 정리합니다.
요약: 일반 배포는
wrangler.toml또는 Wrangler 설정에서 assets 디렉터리를 지정하는 흐름이 우선입니다. 직접 업로드는 자체 배포 버튼, 사내 빌드 파이프라인, 외부 대시보드 연동처럼 프로그램으로 업로드를 제어해야 할 때 쓰는 고급 선택지입니다. 화면 이름, 플랜별 한도, 기능명은 Cloudflare 업데이트에 따라 달라질 수 있으니 최종 적용 전 공식 문서를 다시 확인하세요.
1. Cloudflare Workers Static Assets가 맞는 상황
Cloudflare Workers Static Assets는 HTML, CSS, JavaScript, 이미지, 폰트 같은 정적 파일을 Worker와 함께 배포하려는 상황에 잘 맞습니다. 예를 들어 React나 Vite로 빌드한 dist 폴더를 전 세계 엣지에서 서빙하고, 특정 경로에서는 Worker가 API 응답이나 리다이렉트 같은 로직을 처리하게 만들 수 있습니다. 이전에는 정적 사이트는 Pages, 로직은 Workers로 나눠 생각하는 경우가 많았지만, 작은 제품이나 사내 도구는 한 프로젝트 안에서 정리하는 편이 운영하기 쉽습니다.
처음 판단할 때는 “정적 파일만 있나, 아니면 요청마다 계산해야 하는 로직이 있나”를 보세요. 순수 블로그나 문서 사이트라면 정적 배포만으로도 충분할 수 있습니다. 반대로 로그인 후 사용자별 화면, 폼 제출 처리, 간단한 프록시, 헤더 제어, 캐시 조건 분기처럼 요청 처리 로직이 필요하면 Workers와 Static Assets 조합이 자연스럽습니다. 이 조합은 사이트 속도 개선뿐 아니라 배포 단위를 줄이는 데도 도움이 됩니다.
2. 기본 구조: assets 폴더와 Worker 로직 분리
가장 단순한 구조는 프로젝트 루트 아래에 src 폴더와 public 또는 dist 폴더를 나누는 방식입니다. src에는 Worker 코드가 들어가고, 빌드 결과물은 dist에 모입니다. Cloudflare 문서에서 말하는 assets 디렉터리는 이 빌드 결과 폴더를 가리키는 설정입니다. 프레임워크마다 이름이 다르므로 Vite는 dist, 일부 정적 생성기는 public 또는 build를 쓰는 식으로 맞추면 됩니다.
중요한 점은 소스 파일과 배포 파일을 섞지 않는 것입니다. 팀원이 이미지를 바꾸거나 CSS를 수정했을 때 어떤 폴더가 실제 배포되는지 헷갈리면, 이전 파일이 계속 보이거나 빌드 결과가 누락될 수 있습니다. 그래서 README에 “배포 대상은 dist, 수정 대상은 src”처럼 적어 두면 좋습니다. 사내 템플릿으로 만들 경우에는 폴더 이름을 고정하고, 빌드 명령도 하나로 통일하는 편이 안전합니다.
3. Wrangler 설정에서 먼저 확인할 항목
Wrangler는 Cloudflare Workers 프로젝트를 로컬에서 빌드하고 배포하는 CLI 도구입니다. Static Assets 배포를 시작할 때는 계정 연결보다 먼저 설정 파일을 읽기 쉽게 만드는 것이 좋습니다. 프로젝트 이름, main 스크립트 위치, compatibility date, assets 디렉터리, 개발 서버 명령을 한곳에 정리해 두면 나중에 자동 배포로 옮길 때도 수월합니다. 설정 파일은 팀원이 가장 자주 보는 문서 역할도 하므로 주석을 과하게 넣기보다는 README에서 설명하는 편이 좋습니다.
확인 순서는 다음과 같습니다. 첫째, 로컬 빌드가 성공하는지 봅니다. 둘째, 빌드 결과 폴더가 실제로 생기는지 확인합니다. 셋째, Wrangler 설정의 assets 경로가 그 폴더를 가리키는지 확인합니다. 넷째, Worker 코드가 정적 파일 요청을 막지 않는지 확인합니다. 마지막으로 미리보기 주소에서 새로고침, 하위 경로 접근, 존재하지 않는 경로 처리를 확인합니다. 이 단계만 지켜도 “로컬에서는 보이는데 배포 후에는 빈 화면” 같은 흔한 혼란을 크게 줄일 수 있습니다.
4. 직접 업로드 API는 언제 필요한가
직접 업로드는 이름 때문에 일반 사용자도 꼭 써야 하는 기능처럼 보일 수 있지만, 공식 문서의 설명처럼 프로그램 방식의 통합을 만들 때 쓰는 성격이 강합니다. 예를 들어 고객이 웹 대시보드에서 ZIP 파일을 올리면 사내 시스템이 Workers Assets로 배포해 주는 제품, 여러 팀의 산출물을 한곳에서 승인한 뒤 자동 업로드하는 운영 도구, 외부 빌드 서버가 Wrangler CLI 없이 Cloudflare API로 파일을 올리는 구조라면 직접 업로드를 검토할 만합니다.
반대로 개인 블로그, 회사 소개 페이지, 마케팅 랜딩페이지, 내부 문서 사이트를 배포하는 정도라면 Wrangler 기반 배포가 먼저입니다. 직접 업로드는 토큰 권한, 파일 매니페스트, 업로드 세션, 오류 재시도 같은 관리 포인트가 늘어납니다. “클릭 한 번으로 배포”를 만들고 싶다는 이유만으로 바로 API부터 붙이면 유지 보수가 어려워질 수 있습니다. 먼저 CLI로 안정적인 배포 단위를 만들고, 반복 횟수가 많아졌을 때 API 자동화를 붙이는 순서가 좋습니다.
5. 배포 전 체크리스트
- 빌드 결과 폴더가 비어 있지 않은지 확인합니다.
- HTML에서 참조하는 CSS, JS, 이미지 경로가 상대 경로 또는 배포 경로와 맞는지 확인합니다.
- 새로고침했을 때 SPA 라우팅이 깨지지 않는지 확인합니다.
- 민감한 로컬 파일, 원본 디자인 파일, 테스트 데이터가 assets 폴더에 섞이지 않았는지 확인합니다.
- 캐시가 강하게 남아도 되는 파일과 즉시 바뀌어야 하는 파일을 구분합니다.
- 배포 토큰은 필요한 권한만 갖도록 분리하고, 팀 공용 문서에 값 자체를 적지 않습니다.
이 체크리스트에서 가장 자주 놓치는 부분은 불필요한 파일 포함입니다. 정적 파일 폴더를 넓게 잡으면 원본 이미지, 임시 JSON, 실험용 HTML까지 함께 올라갈 수 있습니다. 그래서 dist처럼 빌드 산출물만 들어가는 폴더를 배포 대상으로 지정하는 것이 편합니다. 수동으로 파일을 복사하는 구조라면 배포 전 정리 명령을 추가하거나, 빌드 스크립트가 항상 깨끗한 폴더를 다시 만들게 구성하세요.
6. 설정 선택지 비교표
| 방식 | 추천 상황 | 장점 | 주의할 점 |
|---|---|---|---|
| Wrangler assets 설정 | 일반 웹앱, 랜딩페이지, 문서 사이트 | 설정이 단순하고 로컬 확인이 쉽다 | 빌드 폴더 경로를 정확히 맞춰야 한다 |
| Git 기반 자동 배포 | 팀 협업, 리뷰 후 배포 | 변경 이력이 남고 반복 운영이 쉽다 | 브랜치 규칙과 빌드 명령을 정해야 한다 |
| 직접 업로드 API | 자체 배포 제품, 사내 통합 도구 | 외부 시스템과 세밀하게 연결할 수 있다 | 권한, 재시도, 오류 로그를 직접 관리해야 한다 |
| 정적 사이트 전용 호스팅 | Worker 로직이 거의 없는 사이트 | 운영 개념이 단순하다 | 요청별 로직 확장이 필요하면 구조를 바꿔야 한다 |
처음부터 완벽한 구조를 고르려고 하기보다, 지금 필요한 요청 처리 수준을 기준으로 고르면 됩니다. “정적 파일을 빠르게 배포하고 약간의 로직을 붙인다”가 목표라면 Wrangler assets 설정이 출발점입니다. “여러 사용자가 자신의 프로젝트를 업로드하는 서비스”처럼 배포 자체가 제품 기능이라면 직접 업로드 API가 후보가 됩니다.
7. 캐시와 경로 처리에서 자주 생기는 혼란
정적 파일 배포에서 화면이 오래된 것처럼 보일 때는 코드 오류보다 캐시와 파일명 문제가 원인인 경우가 많습니다. 빌드 도구가 파일명에 해시를 붙이면 새 배포 때마다 다른 파일명으로 바뀌어 브라우저 캐시 혼란이 줄어듭니다. 반대로 app.js처럼 항상 같은 이름을 쓰면 사용자가 이전 파일을 잠시 볼 수 있습니다. 중요한 공지 페이지나 빠르게 바뀌는 파일은 캐시 전략을 별도로 점검하세요.
SPA 라우팅도 확인이 필요합니다. 예를 들어 /settings 같은 경로를 브라우저에서 직접 열었을 때 서버가 실제 파일을 찾으려 하면 404가 날 수 있습니다. 이때는 Worker 로직이나 프레임워크 설정에서 존재하지 않는 페이지 요청을 앱 진입 파일로 넘기는 처리가 필요합니다. 정적 파일과 Worker가 함께 있을 때는 어느 요청을 파일로 처리하고 어느 요청을 로직으로 처리할지 규칙을 짧게 문서화해 두는 것이 좋습니다.
8. 팀 운영 문서에 남겨야 할 내용
배포가 한 번 성공했다고 끝내면 다음 수정 때 다시 헤매기 쉽습니다. 팀 문서에는 최소한 빌드 명령, 배포 명령, assets 폴더, 환경별 프로젝트 이름, 미리보기 확인 주소, 롤백 방법을 남기세요. 또한 “직접 업로드 API는 현재 사용하지 않음”처럼 쓰지 않는 선택지도 적어 두면, 나중에 다른 담당자가 문서를 보고 불필요한 기능을 붙이는 일을 줄일 수 있습니다.
운영 문서의 핵심은 길이가 아니라 재현성입니다. 새 팀원이 저장소를 받고 npm install, npm run build, wrangler deploy 같은 순서로 따라 했을 때 같은 결과가 나와야 합니다. 만약 계정 권한이나 프로젝트 연결이 필요한 경우에는 값 자체가 아니라 요청 경로와 담당자만 적습니다. 배포 토큰이나 내부 주소를 공개 문서에 적는 방식은 피하는 것이 좋습니다.
9. 비용과 기능 변경 가능성 고지
Cloudflare의 화면 구성, 메뉴 이름, 무료·유료 플랜별 한도, Workers와 Static Assets 관련 세부 기능은 시점에 따라 바뀔 수 있습니다. 이 글은 공식 문서와 공개 검색 결과를 바탕으로 설정 순서를 설명한 실무 체크리스트이며, 실제 적용 전에는 현재 계정의 대시보드와 Cloudflare 공식 문서를 함께 확인해야 합니다. 특히 팀 계정, 조직 권한, 빌드 파이프라인, API 토큰 범위는 운영 환경마다 다르게 설계될 수 있습니다.
또한 직접 업로드 API는 편리해 보이지만 배포 실패 처리, 로그 저장, 사용자 알림, 파일 크기 제한 확인 같은 주변 작업이 필요합니다. 단순히 “CLI를 쓰지 않기 위해” 도입하기보다는, 자체 서비스나 반복 배포 도구 안에서 업로드 과정을 제품 기능으로 제공해야 하는지부터 판단하세요. 그 기준이 명확하면 불필요한 복잡도를 줄이고, Static Assets의 장점을 더 안정적으로 활용할 수 있습니다.
FAQ
Q1. Cloudflare Workers Static Assets와 Pages는 어떻게 골라야 하나요?
정적 사이트 중심이고 별도 Worker 로직이 거의 없다면 Pages가 단순할 수 있습니다. 정적 파일과 요청 처리 로직을 한 프로젝트 단위로 묶고 싶다면 Workers Static Assets를 검토하세요.
Q2. 직접 업로드 API를 쓰면 Wrangler가 필요 없나요?
일부 자동화에서는 Wrangler 없이 API로 업로드할 수 있지만, 처음 설정과 검증은 Wrangler 방식이 훨씬 이해하기 쉽습니다. API는 배포 시스템을 직접 만들 때 선택하는 고급 흐름으로 보는 것이 좋습니다.
Q3. assets 폴더는 public과 dist 중 무엇으로 잡아야 하나요?
프레임워크가 실제로 배포용 파일을 만들어 내는 폴더를 지정하면 됩니다. Vite처럼 빌드 후 dist가 생기는 구조라면 dist를 지정하는 편이 일반적입니다.
Q4. 배포 후 CSS나 이미지가 안 보이면 무엇부터 확인해야 하나요?
빌드 결과 폴더에 파일이 있는지, HTML의 참조 경로가 맞는지, 배포 대상 폴더가 올바른지, 캐시 때문에 이전 파일이 보이는지 순서대로 확인하세요.
Q5. 사내 대시보드에서 고객별 정적 파일을 올리는 구조에도 쓸 수 있나요?
가능성은 있습니다. 다만 그 경우 직접 업로드 API, 권한 분리, 업로드 로그, 실패 재시도, 사용자 알림 같은 운영 기능을 함께 설계해야 합니다.
마무리: 먼저 단순한 배포 단위를 만들기
Cloudflare Workers Static Assets 설정의 핵심은 정적 파일 폴더와 Worker 로직의 역할을 분명히 나누는 것입니다. 처음에는 Wrangler로 빌드 결과 폴더를 연결하고, 미리보기에서 경로와 캐시를 확인한 뒤, 팀 문서에 배포 순서를 남기세요. 직접 업로드 API는 반복 배포가 제품 기능이 되었을 때 검토해도 늦지 않습니다. 이 순서로 접근하면 작은 프로젝트는 빠르게 시작하고, 커지는 프로젝트는 자동화로 자연스럽게 확장할 수 있습니다.
