Cloudflare 이전의 첫 단계는 “GitHub에 커밋하면 Cloudflare가 알아서 Hugo를 돌려 배포한다"를 만드는 것이었다. Workers Builds는 저장소를 연결하면 빌드 명령과 배포 명령을 실행해 준다. 간단해 보였지만, 폰에서 만들던 결과물과 똑같이 나오게 하려면 네 가지를 못 박아야 했다.

빌드 명령은 스크립트 하나로

wrangler.jsonc의 build.command에 bash scripts/cf-build.sh를 넣었다. Cloudflare 빌드 환경에는 Hugo가 없으므로 스크립트가 직접 내려받는다.

PIN="${MHUB_HUGO_VERSION:-0.154.5}"
curl -fsSL -o hugo.tar.gz \
  "https://github.com/gohugoio/hugo/releases/download/v${PIN}/hugo_extended_${PIN}_linux-amd64.tar.gz"
tar -xz -f hugo.tar.gz hugo
export TZ=Asia/Seoul
hugo --minify

버전 변수 이름을 HUGO_VERSION이 아니라 MHUB_HUGO_VERSION으로 한 데는 이유가 있다. Cloudflare 대시보드의 빌드 변수에 HUGO_VERSION이 있으면 플랫폼이 그 값을 다른 의미로 읽을 수 있어서, 내 스크립트만 읽는 전용 이름을 쓰는 편이 안전했다.

왜 버전을 폰과 똑같이 고정했나

처음에는 최신 Hugo를 받아 썼는데 사이트맵이 미묘하게 달랐다. 폰의 Hugo 0.154.5와 다른 버전은 사이트맵의 lastmod에 예약 글 날짜가 섞이거나 RSS와 구조화 데이터의 공백 처리가 달랐다. 겉보기엔 같은 사이트인데 검색엔진이 보는 파일이 달라지는 셈이라, 폰과 같은 0.154.5로 고정했다. 나중에는 내려받은 파일의 SHA-256까지 확인하게 바꿨다. 그 이야기는 보안 보강 편에서 다룬다.

시간대

폰은 한국 시간대에서 빌드했다. Cloudflare 빌드 환경은 UTC라서 그대로 두면 글 날짜 툴팁의 시간대 표기가 달라진다. TZ=Asia/Seoul을 빌드 직전에 넣어 폰과 같은 결과를 냈다. 글 자체의 날짜는 모두 +09:00 오프셋을 명시하고 있어 공개 시각에는 영향이 없지만, 보이는 표기까지 같아야 “포팅이 정확하다"고 말할 수 있었다.

previews 블록이 없으면 비프로덕션 빌드가 깨진다

Workers Builds는 main이 아닌 브랜치에서는 배포 대신 미리보기(wrangler versions upload에 해당)를 만든다. 그런데 wrangler.jsonc에 previews 설정이 아예 없으면 그 단계가 실패한다. 빈 객체라도 있어야 했다.

"previews": {}

이걸 넣고 나서야 PR마다 Cloudflare가 미리보기 배포 결과를 댓글로 달아 주기 시작했다. 병합 전에 빌드가 통과하는지 보는 안전망이 하나 생긴 셈이다.

workers.dev가 조용히 꺼지는 함정

라우트(mhub.uk/*)를 추가하고 배포했더니 확인용으로 쓰던 workers.dev 주소가 404가 됐다. 원인은 wrangler의 기본 동작이었다. 설정에 workers_dev를 명시하지 않은 채 라우트를 넣으면 wrangler가 “라우트가 있으니 workers.dev는 필요 없겠지"라고 판단해 자동으로 끈다. "workers_dev": true를 명시해서 복구했다. 이 주소는 도메인을 바꾸기 전에 새 배포를 시험하는 통로라서 꼭 살아 있어야 했다.

호스트가 다르면 정적 파일만

Worker 코드 쪽에서도 한 줄이 필요했다. mhub.uk가 아닌 호스트(workers.dev 등)로 들어온 요청은 API나 관리 화면 분기를 타지 않고 항상 정적 파일만 내주게 했다. 확인용 주소에서 실수로 데이터베이스를 건드리거나 관리 기능이 열리는 일을 막기 위해서다.

얻은 것

이 단계가 끝나자 “커밋 → 1분 안팎 → 사이트 반영"이 됐다. 폰 시절에는 글을 저장하면 5초면 보였지만 그 5초는 폰이 켜져 있을 때만 유효했다. 1분은 느리지만 폰이 꺼져 있어도, 내가 자고 있어도 돌아간다. 다음 글은 그 Worker 앞단을 어떻게 “일단 전부 폰으로 통과시키는” 모양으로 시작해 무중단으로 바꿔 나갔는지다.