Last updated on

Cloudflare Pages 404 해결: index가 없을 때 가장 먼저 확인할 설정

Cloudflare Pages에 정적 블로그를 올렸는데 메인 주소에서 바로 404 Not Found가 뜨면, 많은 사람들이 먼저 index.html이 생성되지 않았다고 생각한다. 하지만 실제 원인은 파일이 없어서가 아니라 빌드 설정이 비어 있거나 잘못된 경우가 훨씬 많다.

이 글은 Astro 같은 정적 블로그를 Cloudflare Pages에 연결했는데 메인 페이지가 열리지 않을 때, 가장 먼저 확인해야 할 항목을 짧고 실전적으로 정리한 가이드다.

결론부터

정적 블로그에서 메인 페이지 404가 뜰 때 가장 먼저 확인할 것은 아래 네 가지다.

  • Production branch
  • Build command
  • Build output directory
  • Root directory

Astro 프로젝트라면 보통 아래 값이 맞다.

  • Production branch: main
  • Build command: npm run build
  • Build output directory: dist
  • Root directory: 비워두기

왜 404가 뜨는가

Cloudflare Pages는 GitHub 저장소를 읽어 자동으로 빌드한 뒤, 지정된 출력 폴더를 실제 사이트로 배포한다. 문제는 이 과정에서 무엇을 빌드할지, 어디에 결과물이 나오는지를 모르면 사이트 루트에 내보낼 파일을 찾지 못한다는 점이다.

즉 아래 같은 경우에 404가 자주 발생한다.

  • 저장소는 연결됐지만 Build command가 비어 있음
  • Build output directory가 비어 있음
  • Root directory를 잘못 넣어서 실제 프로젝트 루트를 벗어남
  • 이전 템플릿 프로젝트를 기준으로 설정이 남아 있음

이 경우 로컬에서는 분명히 dist/index.html이 있는데도, Cloudflare는 그 파일을 배포 대상으로 잡지 못해서 메인 주소에서 404를 반환할 수 있다.

1. Git repository가 맞는지 확인

가장 먼저 볼 것은 Cloudflare Pages 프로젝트가 실제로 올린 저장소를 보고 있는지다.

예를 들어 GitHub 저장소가 mempop0002-lgtm/blog인데, Pages 프로젝트가 예전 테스트 저장소나 다른 브랜치를 보고 있다면 새 코드가 배포되지 않는다.

즉 첫 번째 체크는 항상 이거다.

  • 현재 Pages 프로젝트가 어떤 GitHub 저장소를 보고 있는가
  • Production branch가 main인가

2. Build command가 비어 있지 않은지 확인

Astro 블로그는 정적 파일을 만들기 위해 빌드가 필요하다. 로컬에서 npm run build를 쓰고 있다면 Cloudflare Pages도 같은 명령을 알아야 한다.

이 값이 비어 있으면 Cloudflare는 정적 결과물을 생성하지 못한다.

Astro 기준으로는 보통:

npm run build

를 넣으면 된다.

3. Build output directory가 dist인지 확인

Astro 기본 정적 산출물은 dist 폴더에 생성된다. 따라서 Cloudflare Pages는 빌드 후 dist를 실제 배포 폴더로 봐야 한다.

이 값이 비어 있거나 잘못되면 결과적으로 메인 페이지가 있어도 서비스 파일로 인식되지 않을 수 있다.

Astro에서는 보통 아래가 맞다.

dist

4. Root directory는 괜히 건드리지 않는 편이 낫다

저장소 루트 자체가 Astro 프로젝트라면 Root directory는 보통 비워두는 편이 맞다. 이 값을 하위 폴더로 잘못 지정하면 Cloudflare는 엉뚱한 경로에서 package.json이나 dist를 찾게 된다.

특히 한 저장소 안에 여러 프로젝트가 있는 경우가 아니라면, 루트 디렉터리는 비워두는 것이 가장 안전하다.

5. 설정을 바꿨는데도 자동 빌드가 안 되는 이유

이 부분도 많이 헷갈린다. Cloudflare Pages는 보통 GitHub에 새 commit이 push될 때 자동 빌드를 트리거한다. 반면 설정 변경 자체는 항상 자동 재배포를 일으키지 않는다.

즉 이런 흐름이 자연스럽다.

  • 설정 변경
  • 자동 빌드 안 뜸
  • Redeploy 또는 Retry deployment 직접 실행

만약 버튼이 애매하면 가장 확실한 방법은 새 커밋을 하나 더 올리는 것이다. 작은 문구 수정이라도 git push를 하면 Cloudflare가 새 빌드를 다시 잡는다.

6. 실제 점검 순서

Cloudflare Pages에서 메인 주소가 404일 때는 아래 순서로 보면 된다.

  1. Workers & Pages에서 해당 프로젝트 선택
  2. Settings
  3. Builds & deployments
  4. 아래 값 확인
    • Production branch: main
    • Build command: npm run build
    • Build output directory: dist
    • Root directory: 비움
  5. Deployments 탭으로 이동
  6. 최근 배포에 대해 Redeploy 또는 Retry deployment

이 순서만 지켜도 대부분의 404 문제는 초기에 정리된다.

마무리

Cloudflare Pages에서 메인 페이지 404가 뜬다고 해서 바로 index.html 자체를 의심할 필요는 없다. 정적 블로그에서는 오히려 빌드 설정 공란, 출력 폴더 설정 오류, 루트 경로 오설정이 더 흔한 원인이다.

Astro 블로그 기준으로는 아래만 기억하면 된다.

  • Build command: npm run build
  • Build output directory: dist
  • Root directory: 비워두기

이 세 가지를 맞춘 뒤 다시 배포하면, 생각보다 많은 문제가 바로 해결된다.