로컬에서는 잘 되던 빌드가 Git에 푸시하면 Cloudflare Pages에서 Failed로 끝나는 경우가 있습니다. 사이트에는 이전 배포가 그대로 남아 있고, 무엇이 문제인지는 빌드 로그에만 적혀 있습니다.
Pages 배포는 환경 초기화, 저장소 클론, 애플리케이션 빌드, 글로벌 네트워크 배포의 4단계로 진행되고, 한 단계라도 0이 아닌 종료 코드로 끝나면 배포가 중단됩니다. 그래서 로그에서 어느 단계가 실패했는지부터 보면 원인 범위가 크게 줄어듭니다.
빌드 로그 확인 경로와 단계별 실패 원인
Cloudflare 대시보드의 Workers & Pages에서 프로젝트를 선택하고 Deployments > View details > Build log로 들어가면 단계별 로그가 나옵니다. Cloudflare 문서가 단계별로 안내하는 원인과 조치는 아래와 같습니다.
| 실패한 단계 | 흔한 원인 | 조치 |
|---|---|---|
| 환경 초기화 | Git 통합 설치 오류 | GitHub·GitLab의 Cloudflare Pages 앱을 제거하고 다시 승인 |
| 저장소 클론 | Git LFS 용량 부족, .gitmodules 설정 오류 |
LFS 사용량 확인, .gitmodules에 path와 url이 모두 있는지 확인 |
| 애플리케이션 빌드 | 빌드 명령, 출력 폴더, 환경 변수 설정 오류 | 프로젝트 설정 점검, 커밋 메시지의 이모지·특수문자 제거 |
| 글로벌 네트워크 배포 | Pages Functions 설정 오류 또는 Cloudflare 측 문제 | Functions 설정 확인, Cloudflare Status 확인 |
이 표 밖에서 자주 만나는 실패는 아래 세 가지입니다. 모두 빌드 단계의 로그에 나타납니다.
- 락 파일 불일치:
npm ERR! code EUSAGE와 함께npm ci가package.json과package-lock.json이 맞지 않는다고 알려 줍니다. - 대소문자 오류:
Module not found: Can't resolve ... - 시간 초과: 빌드는 모든 플랜에서 20분을 넘기면 중단됩니다.
월 빌드 횟수는 Free 500회, Pro 5,000회, Business 20,000회이며 프로젝트별이 아니라 계정 단위로 집계됩니다. 파일 하나의 크기는 25 MiB까지, 계정당 프로젝트는 100개까지입니다.
로컬 환경과 Pages 빌드 환경의 차이
로컬에서는 되고 Pages에서만 실패한다면 대개 환경 차이입니다. 가장 흔한 세 가지를 순서대로 확인합니다.
락 파일과 설치 명령
빌드 로그 초반에 Pages가 실행한 설치 명령이 찍힙니다. npm clean-install(npm ci)이 보인다면 package-lock.json이 package.json과 정확히 맞아야 통과합니다. package.json만 고치고 락 파일을 커밋하지 않은 경우가 가장 흔합니다.
파일명 대소문자
Pages의 빌드 환경은 리눅스(Ubuntu 22.04)라서 파일명 대소문자를 구분합니다. macOS나 Windows에서는 import Header from './header'가 Header.jsx를 찾아도 리눅스에서는 Module not found가 납니다. 파일명과 import 경로를 같은 철자로 맞추세요.
Node.js 버전
빌드 시스템 버전에 따라 기본 Node.js가 다릅니다. Cloudflare 문서 기준으로 v3는 Node.js 22.x, v2는 18.17.1이 기본입니다. 같은 문서에 v2가 2027년 2월 23일에 v3로 자동 이전된다고 적혀 있으므로, 오래된 프로젝트는 그 전에 새 버전에서 빌드가 되는지 확인해 두는 편이 안전합니다. 버전은 두 방법으로 고정합니다.
- 프로젝트 루트에
.nvmrc또는.node-version파일을 둡니다. Settings > Environment variables에서NODE_VERSION을 지정합니다.
# .nvmrc (프로젝트 루트)
22
문서에는 두 방법이 함께 있을 때의 우선순위가 적혀 있지 않습니다. 한 가지만 쓰고, 로그 상단에 찍힌 Node 버전으로 적용 여부를 확인하세요.
빌드 중에 번들에 들어가야 하는 값은 Settings > Environment variables에 등록합니다. 변수가 비어 있어 빌드가 중단되는 경우도 많습니다. Workers 런타임의 변수 문제는 Cloudflare Workers 환경 변수가 undefined일 때 확인할 것을 참고하세요.
해결 절차
- 빌드 로그에서 어느 단계가 실패했는지와 마지막 오류 메시지를 확인합니다.
- 로컬에서 락 파일을 맞추고
npm ci와 빌드 명령이 통과하는지 확인합니다. - Node.js 버전과 환경 변수, 빌드 명령, 출력 폴더를 Pages 설정과 일치시킵니다.
락 파일 동기화
# 락 파일을 다시 만들고 Pages와 같은 방식으로 설치해 보기
rm -rf node_modules package-lock.json
npm install
npm ci
npm ci가 통과하면 package-lock.json을 함께 커밋해서 푸시합니다.
빌드 명령과 출력 폴더
프레임워크 프리셋의 빌드 명령과 출력 폴더를 그대로 입력합니다. 예를 들어 Vite 기반 React는 npm run build에 출력 폴더 dist입니다. 종료 코드가 0이 아니면 배포가 중단됩니다.
모노레포의 Build watch paths
모노레포에서는 관련 없는 폴더가 바뀔 때마다 빌드가 도는 것을 막기 위해 Settings > Build > Build watch paths를 지정합니다. 기본값은 모든 파일(*)을 포함하는 것입니다. *는 /를 포함한 모든 문자와 일치하므로 하위 폴더까지 한 번에 지정할 수 있습니다.
# 포함 경로 예시: apps/web 아래가 바뀔 때만 빌드
apps/web/*
수정 후 배포 검증
Build log에서 모든 단계가 성공했는지 확인- 로그 상단의 Node.js 버전이
.nvmrc또는NODE_VERSION과 같은지 확인 - 파일 하나가 25 MiB를 넘지 않는지 확인
- 빌드 시간이 20분 한도에 가깝지 않은지 확인
환경 초기화 단계에서 계속 실패하면 Git 통합 문제일 가능성이 큽니다. GitHub나 GitLab의 애플리케이션 설정에서 Cloudflare Pages 앱을 제거한 뒤 다시 승인하세요. 코드 문제가 아닌데 배포 단계에서만 실패한다면 Cloudflare Status 페이지에서 장애 여부를 확인합니다.
빌드 시간과 횟수 줄이기
빌드 횟수는 계정 전체에서 세기 때문에 프로젝트가 여러 개면 한도가 빨리 소진됩니다. 오타 수정마다 푸시하기보다 로컬에서 확인한 뒤 묶어서 푸시하는 편이 좋습니다.
빌드 캐시
Settings > Build에서 빌드 캐시를 켜면 반복 빌드가 빨라집니다. 빌드 시스템 v2 이상이 필요하고, 지원 프레임워크는 Astro, Docusaurus, Eleventy, Gatsby, Hugo, Next.js, Nuxt, SvelteKit입니다. 캐시 대상은 패키지 매니저 캐시(npm은 .npm)와 프레임워크별 캐시이며 node_modules 폴더 자체가 아닙니다.
Direct Upload
미리 빌드한 결과물을 올리는 Direct Upload는 Cloudflare가 빌드를 수행하지 않으므로 월 빌드 횟수와 20분 빌드 제한이 걸리지 않습니다. 다만 프로젝트를 Direct Upload로 만들면 나중에 Git 통합으로 바꿀 수 없으므로, 테스트용 프로젝트를 따로 만들어 쓰세요.
# 로컬에서 빌드한 뒤 결과 폴더를 업로드
npm run build
wrangler pages deploy ./dist --project-name=my-web-project
예전 글에 자주 나오는 wrangler pages publish는 현재 문서에서 쓰는 명령이 아닙니다. wrangler pages deploy를 쓰세요.
빌드 스크립트에서는 Pages가 주입하는 CF_PAGES, CF_PAGES_BRANCH, CF_PAGES_COMMIT_SHA, CF_PAGES_URL 변수로 브랜치별 동작을 나눌 수 있습니다.
자주 묻는 질문 (FAQ)
Q. 로컬 npm run build는 되는데 Pages에서만 npm ci 오류가 납니다.
npm ci는 package.json과 package-lock.json이 정확히 맞아야 통과합니다. package.json만 수정하고 락 파일을 갱신하지 않았을 가능성이 가장 높습니다. 로컬에서 npm install을 실행하고 갱신된 package-lock.json을 커밋하세요.
Q. 클론 단계에서 바로 실패합니다.
문서에 안내된 원인은 Git LFS 용량 부족과 .gitmodules 설정 오류입니다. LFS 사용량을 확인하고, 서브모듈마다 path와 url이 모두 있는지 확인하세요. 통합 권한 문제라면 Git 앱을 재승인합니다.
Q. 월 500회 빌드 한도를 쓰지 않고 배포를 시험할 수 있나요?
Direct Upload 프로젝트에 wrangler pages deploy로 올리면 Cloudflare 빌드를 거치지 않습니다. Git 통합 프로젝트에서는 쓸 수 없고, 한 번 Direct Upload로 만든 프로젝트는 Git 통합으로 바꿀 수 없다는 점을 알아 두세요.

