Cloudflare Workers Static Assets 운용 가이드 — 라우팅과 캐시를 안정적으로 잡는 방법

Cloudflare에서 정적 파일을 붙이는 방식은 이제 “파일 서빙” 문제가 아니라 라우팅 설계 문제다. 같은 Workers라도 assets 설정을 어떻게 하느냐에 따라 요청 흐름이 완전히 달라진다.

한 줄 결론부터

• 정적 사이트 중심이면: 기본 자산 우선 라우팅이 가장 단순하다.
• 인증/미들웨어가 있으면: run_worker_first가 필요하다.
• SPA 라우팅이면: not_found_handling = "single-page-application"이 사실상 필수다.

왜 헷갈리기 쉬운가

Workers Static Assets는 설정이 짧아서 쉬워 보이지만, 실제로는 “자산이 먼저 응답할지, Worker가 먼저 실행될지”가 서비스 동작을 좌우한다.

[💡 잠깐! 이 용어는?] run_worker_first: 정적 파일 매칭 전에 Worker를 먼저 실행하는 옵션이다. 인증, 헤더 주입, A/B 라우팅 같은 미들웨어 성격 작업에 필요하다.

라우팅 옵션 비교

비유하면 기본값은 무인 키오스크고, run_worker_first는 입구에 안내 직원이 서 있는 구조다.

실무 설정 예시

name = "my-app"
main = "src/index.ts"
compatibility_date = "2026-02-20"
 
[assets]
directory = "./dist"
not_found_handling = "single-page-application"
run_worker_first = true

이 조합은 “SPA + 인증 미들웨어” 조합에서 자주 쓰인다.

자주 터지는 문제와 해결

1) 로그인 페이지가 정적 파일로만 내려오는 문제

원인: 기본 자산 우선 라우팅이라 Worker 인증 로직이 실행되지 않음. 해결: run_worker_first = true 또는 경로별 선실행 규칙 적용.

2) SPA 새로고침 404

원인: /dashboard/settings 같은 경로가 실제 파일이 아니라서 매칭 실패. 해결: not_found_handling = "single-page-application"로 폴백 설정.

3) 캐시가 너무 오래 남는 문제

원인: 정적 자산 캐시 정책과 API 응답 캐시를 같은 기준으로 처리. 해결: 해시된 자산(app.abc123.js)은 장기 캐시, HTML/API는 짧은 캐시로 분리.

운영 체크리스트

• 자산 우선/Worker 우선 정책을 문서화했나
• SPA 폴백 경로를 명시했나
• 인증이 필요한 경로에서 Worker 선실행이 보장되나
• 자산 캐시와 API 캐시를 분리했나

이 네 가지를 먼저 정리하면 배포 후 장애 대부분을 줄일 수 있다.

마무리

Workers Static Assets는 “정적 파일 편의 기능”이 아니라 엣지 라우팅 전략의 일부다. 설정 몇 줄이지만, 순서 하나 잘못 잡으면 인증 누락/404/캐시 꼬임이 같이 터진다. 먼저 요청 흐름을 설계하고 설정을 붙이는 순서가 안전하다.

참고:

• Workers Static Assets: https://developers.cloudflare.com/workers/static-assets/
• Routing + worker first: https://developers.cloudflare.com/workers/static-assets/routing/worker-script/
• Migrate from Pages: https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/