Cloudflare Pages와 Workers를 같이 배포할 때

정적 블로그만 올리면 Workers assets 하나로 끝입니다. 그런데 프론트(Pages)와 API Worker, 가끔 Firebase까지 한 레포에서 굴리는 프로젝트는 배포 순서를 안 지키면 “화면은 새것인데 API는 옛것”이 됩니다. 노션 “클라우드플레어 배포” 페이지에 그 순서를 명령어로 잔뜩 적어 두었고, 이 글은 그 운영 메모를 일반화한 것입니다. 토큰·시크릿 값은 제외했습니다.

역할을 먼저 나눈다

조각	하는 일	배포 수단 예
웹 UI	HTML/JS 번들	`wrangler pages deploy` 또는 Git 연동 Pages
API Worker	JSON, 캐시, 크론	`wrangler deploy` (별도 config)
데이터 워밍	Worker 캐시/ingest	`npm run …:ingest` 같은 후처리
(선택) Firebase	호스팅·Functions 잔여	`firebase deploy`

블로그(서민혁닷컴)는 위 표의 UI만 Workers assets로 합친 케이스입니다. 리뷰올처럼 Pages + API를 나눈 경우에는 깃 푸시 ≠ API 배포인 날이 많습니다. Actions로 Pages만 돌리고 Worker는 로컬/npm run cf:api:deploy로 따로 친 적이 있습니다.

손으로 한 번에 확인할 때

메모에 있던 통합 흐름을 뼈대만 남기면:

npm ci
npm run build
npx wrangler pages deploy dist --project-name <pages-project>
npx wrangler deploy --config cloudflare/api/wrangler.toml
# 캐시/ingest가 있으면
set -a && source .secrets/worker_ingest.env && set +a
npm run cf:ingest:run

.secrets/는 Git에 넣지 않습니다. 환경 변수 주입 방식은 API 키와 .env와 같습니다.

배포 후 브라우저에서:

화면에 API:WORKER 같은 상태 표시가 있으면 새 빌드인지 본다
Cmd+Shift+R로 강력 새로고침
같은 게시글/상세를 다시 열어 캐시된 JSON이 갱신됐는지 본다

ingest를 안 돌리면 Worker 코드는 새것인데 엣지 캐시만 옛 데이터인 경우가 있었습니다.

Git에만 맡길 때

git add .
git commit -m "배포: 페이지/워커 업데이트"
git push origin main

Pages는 Git 연동으로 따라오고, Worker는 워크플로에 wrangler deploy가 없으면 수동입니다. 저장소의 Actions 탭과 Cloudflare 배포 이력을 같이 보면 “깃은 갔는데 워커는 어제”를 빨리 발견합니다.

로컬 개발 서버가 죽지 않고 남아 있으면:

pkill -f "node server/server.js" || true
npm run dev

같은 식으로 포트를 비우고 다시 띄웁니다.

블로그에 적용할 때

단일 Worker 정적 사이트는 Workers에 정적 사이트 올리기만으로 충분합니다. 이 글은 UI와 API를 나눈 레포를 위한 운영 메모입니다. 명령어 이름은 프로젝트마다 다르니, package.json의 deploy:cf, cf:api:deploy, cf:ingest:run을 기준으로 자신만의 한 줄 스크립트로 묶어 두는 것을 추천합니다. 배포할 때마다 노션에서 복사·붙여넣기 하다 보면 시크릿이 같이 복사됩니다. 스크립트화하는 김에 키는 환경에서만 읽게 바꾸세요.