정적 블로그를 Cloudflare Pages에 올렸다. 배포 목록에는 Success 가 찍혀 있는데 주소로 들어가면 404였다.

HTTP/1.1 404 Not Found
Server: cloudflare

본문은 비어 있었다.

로그에는 아무 문제가 없다

먼저 의심한 건 빌드 실패였다. 그런데 배포 목록의 두 항목 모두 초록색 체크였고, 빌드 로그에도 오류가 없었다.

개별 배포 주소(https://<해시>.<프로젝트>.pages.dev)로 들어가 봐도 똑같이 404였다. 배포는 됐는데 내용이 없는 상태다.

무엇이 배포됐는지 물어본다

“왜 404인가” 대신 “그럼 무엇이 올라가 있나” 를 물어보기로 했다. 있을 법한 경로를 하나씩 찔러 봤다.

for p in / /index.html /robots.txt /package.json /astro.config.mjs; do
  printf "%-20s → %s\n" "$p" "$(curl -s -o /dev/null -w '%{http_code}' "$BASE$p")"
done

/                    → 404
/index.html          → 404
/package.json        → 200   ←
/astro.config.mjs    → 200   ←

소스 파일이 서빙되고 있었다. package.json 과 설정 파일이 200으로 응답한다는 건, 빌드 결과물이 아니라 저장소 루트가 통째로 배포됐다는 뜻이다.

정적 사이트 생성기는 결과물을 dist 같은 별도 폴더에 만든다. 저장소 루트에는 index.html 이 없으니 / 는 당연히 404다.

원인 — 빌드 출력 경로가 비어 있었다

프로젝트 설정을 보니 Build output directory 칸이 비어 있었다.

Build command           npm run build
Build output directory  (비어 있음)     ← 여기

Cloudflare Pages는 이 값이 없으면 저장소 루트를 배포한다. 빌드 명령은 정상 실행됐고 dist 도 만들어졌지만, 아무도 그 폴더를 보지 않았다. 그래서 “성공”이다.

프레임워크 프리셋을 고르면 자동으로 채워지는데, 수동으로 만들면 비어 있을 수 있다.

고친 뒤에도 안 바뀐다

값을 dist 로 채웠는데 여전히 404였다. 설정 변경만으로는 재배포되지 않는다.

Deployments → 최신 배포 → Retry deployment

또는 아무 커밋이나 push하면 새 배포가 걸린다. 나는 후자로 해결했다.

곁다리 — 설정을 저장소에 두려다

설정을 대시보드가 아니라 저장소에 두면 프로젝트를 다시 만들어도 따라온다. Cloudflare Pages는 이걸 지원한다.

name = "my-blog"
pages_build_output_dir = "dist"

시도해 봤지만 이번엔 반영되지 않았다. 원인을 끝까지 파지 않고 대시보드 설정으로 돌아갔는데, 설정이 두 곳에 나뉘면 어느 쪽이 적용됐는지 알기 어려워지는 것이 더 큰 문제라고 봐서다. 한 곳으로 통일했다.

정리

• 배포 상태가 Success 인데 404면 빌드가 아니라 무엇을 배포했는지를 의심한다
• 소스 파일(package.json 등)이 200으로 응답하면 저장소 루트가 배포된 것이다
• 출력 경로가 비어 있으면 Cloudflare Pages는 루트를 배포한다. 정적 생성기를 쓴다면 dist 같은 결과 폴더를 지정해야 한다
• 설정을 바꿔도 자동 재배포되지 않는다. 재시도하거나 새 커밋을 push해야 한다

디버깅에서 “왜 실패했나”보다 “지금 무엇이 있나” 를 먼저 물어보는 게 빨랐다. 로그가 정상이라고 말할 때는 특히 그렇다.