Cloudflare Workers에 정적 사이트 올리는 법

Workers를 API 전용으로만 쓰는 줄 알았는데, 정적 블로그도 잘 올라갑니다. 서민혁닷컴은 Astro로 dist를 만들고, wrangler.jsonc의 assets에 그 폴더를 물려 warpsense-blog라는 Worker 이름으로 배포했습니다. (공개 브랜드와 Worker 이름이 달라도 됩니다. 배포 식별자일 뿐입니다.)

핵심은 소스(src/)가 아니라 빌드 결과를 올리는 것입니다.

지금 쓰는 최소 설정

대략 이런 형태입니다.

{
  "name": "warpsense-blog",
  "compatibility_date": "2026-07-01",
  "assets": {
    "directory": "./dist",
    "html_handling": "drop-trailing-slash",
    "not_found_handling": "404-page"
  }
}

로컬에서는:

npm install
npm run build
npx wrangler deploy

배포가 끝나면 https://<이름>.<계정>.workers.dev로 바로 확인합니다. 이쪽은 대체로 막힘없이 HTML이 내려옵니다. 문제가 생기면 십중 아홉은 directory 경로 오타거나, 빌드 전에 deploy를 돌린 경우입니다. dist/index.html이 있는지부터 봅니다.

html_handling: drop-trailing-slash는 /about/과 /about을 한쪽으로 맞출 때 편합니다. canonical·sitemap과 규칙을 같게 두세요. not_found_handling: 404-page는 없는 글 슬러그에서 커스텀 404를 보여 줍니다.

커스텀 도메인을 붙일 때

Workers 대시보드에서 Custom Domain으로 apex를 붙이면 DNS에 AAAA 100::(프록시) 같은 레코드가 생깁니다. HTTPS는 Cloudflare가 처리합니다.

여기서 한 번 크게 헷갈렸습니다. workers.dev는 200인데 seominhyuk.com만 403 Challenge. 배포가 잘못된 게 아니라 존(Bot Fight) 설정이 HTML 응답 앞에 끼어든 거였습니다. 정적 assets의 ads.txt·robots.txt는 캐시 HIT로 200이 나오는데, HTML·sitemap만 챌린지되는 패턴이라 더 헷갈렸습니다. 도메인 연결 체크는 HTTPS·커스텀 도메인 DNS에, 챌린지 해제는 Bot Fight 글에 적어 두었습니다.

www를 쓰려면 Custom Domain이 API 권한 때문에 안 붙을 때가 있습니다. 그때는 www용 AAAA 100::를 만들고 Workers Route www.도메인/* → 스크립트 이름으로 연결하는 식으로 우회했습니다.

Pages랑 뭐가 다르냐

같은 계정에서 Pages + Worker API를 같이 돌리는 프로젝트(리뷰올 등)도 있습니다. 블로그만이면 Workers assets 하나로도 충분하고, Pages 깃 연동 + API Worker 분리는 Pages와 Workers를 같이 배포할 때에 노션에 정리해 두었던 명령 흐름을 바탕으로 적어 두었습니다.

캐시는 배포 직후 옛 HTML이 남을 수 있습니다. 이상하면 존 캐시 퍼지 후 시크릿 창으로 다시 봅니다.

정리하면, 정적 블로그는 build → assets.directory → wrangler deploy → workers.dev 확인 → 커스텀 도메인 → 봇이 HTML을 받는지 순서로 보면 헛수고가 줄어듭니다.