Cloudflare에서 Pages를 만들려다 Worker가 만들어졌다 초안
Astro로 만든 정적 사이트를 Cloudflare Pages에 올리려고 했다. 예전에도 여러 번 해 본 일이라 5분이면 끝날 줄 알았는데, 프로젝트를 세 번 만들고 두 번 지웠다. 대시보드 화면이 바뀌면서 생긴 함정이 두 개 있었다.
첫 빌드는 35초 만에 실패했다
Workers & Pages에서 Create application을 누르고, 맨 위에 있는 Continue with GitHub로 저장소를 골랐다. 프로젝트는 만들어졌는데 첫 빌드가 바로 실패했다. 빌드 설정을 펼쳐 보니 이렇게 돼 있었다.
| 항목 | 값 |
|---|---|
| Build command | None |
| Deploy command | npx wrangler deploy |
| Root directory | / |
로그는 설치까지 멀쩡했다.
Detected the following tools from environment: npm@10.9.2, nodejs@24.18.0
Installing project dependencies: npm clean-install --progress=false
added 905 packages, and audited 914 packages in 25s
단계별 시간은 Initializing 4초, Cloning 2초, Installing 26초, Deploying 3초였고, 마지막 Deploying에서 멈췄다.
Deploy command라는 칸이 있다는 것부터 이상했다. Pages 설정에는 그런 칸이 없다. Pages는 빌드 명령과 결과물 폴더만 받는다.
만들어진 것은 Worker였다. 지금 Create application 화면의 큰 버튼들은 전부 Worker를 만든다. Worker 빌드는 저장소 루트에서 npx wrangler deploy를 실행하는데, 내 저장소에는 그게 돌아갈 조건이 없었다. 빌드 명령이 None이라 사이트를 빌드하지 않았으니 올릴 dist 폴더가 없다. 루트에 wrangler 설정 파일도 없어서 무엇을 어디에 올릴지 알 수 없다. 그래서 설치는 성공하고 배포에서 실패했다. Retry build를 눌러도 설정이 같으니 결과도 같다.
두 화면은 설정의 칸 이름 하나로 구분된다. Deploy command 칸이 있으면 Worker, Build output directory 칸이 있으면 Pages다.
Pages 입구는 맨 아래 작은 글씨였다
Create application 화면에는 Continue with GitHub, Connect with GitLab, Start with Hello World!, Select a template, Upload your static files 버튼이 있다. Pages로 가는 버튼은 이 중에 없다. 그 아래에 작은 글씨로 이렇게 적혀 있다.
Need to use the legacy Pages workflow? Continue to Pages
이 링크가 Pages 입구다. 내가 기억하던 문구는 “Looking to deploy Pages?”였는데 지금은 달라져 있어서 한 번에 찾지 못했다. 들어가면 익숙한 3단계 화면(Select repository → Set up builds and deployments → Deploy site)이 나온다. 실패한 Worker는 Settings 맨 아래의 Delete로 먼저 지웠다.
저장소 선택 화면에는 새로 만든 저장소가 보이지 않았다. 예전에 Cloudflare GitHub 앱을 설치하면서 Only select repositories로 골라 둔 탓이다. 그때 선택한 저장소만 목록에 나온다. GitHub의 Settings → Applications → Installed GitHub Apps에서 Cloudflare Workers and Pages의 Configure를 누르고 Repository access에 새 저장소를 추가하면 된다. Cloudflare 화면으로 돌아와 새로고침하면 목록에 나타난다.
이번에는 No Git connection
Pages 화면에서 설정을 다 넣고 Save and Deploy를 눌렀더니 빨간 문구가 나왔다.
Your project was created, but its first deployment failed to start. Please try deploying again.
프로젝트 목록에 가 보니 프로젝트는 있는데 저장소 이름이 있어야 할 자리에 No Git connection이라고 적혀 있었다. 프로젝트만 만들어지고 GitHub 연결은 안 됐다.
같은 화면에서 Save and Deploy를 다시 누르면 안 된다. 프로젝트는 이미 만들어진 상태다. 이 프로젝트를 살려 쓸 수도 없다. Cloudflare 문서에 따르면 Git 연결 방식과 직접 업로드 방식은 나중에 서로 바꿀 수 없어서, 연결 없이 만들어진 프로젝트에는 Git을 붙일 수 없다.
그래서 이 프로젝트도 지우고 다시 만들었다. 달라진 건 Project name 하나다. 이 칸의 기본값은 저장소 이름인데, 그 이름은 방금 지운 Worker와 같았다. 이름을 다른 것으로 바꿔서 만들자 Git 연결과 첫 배포가 모두 성공했다.
원인이 정말 이름 충돌이었는지는 확인하지 못했다. 이름만 바꿔서 다시 했을 때 됐다는 것까지가 내가 아는 사실이다.
Project name 칸은 설정 화면 맨 위에 있다. Production branch부터 보이게 스크롤된 상태에서 입력을 시작해서 이 칸이 있는 줄도 몰랐다.
올라간 설정
npm workspaces 모노레포 안의 사이트 하나(sites/hub)를 올리는 설정이다.
| 항목 | 값 |
|---|---|
| Project name | 저장소 이름과 다른 이름 |
| Production branch | main |
| Framework preset | None |
| Build command | cd ../.. && npm ci && npm run build --workspace sites/hub |
| Build output directory | dist |
| Root directory (advanced) | sites/hub |
| Environment variables | NODE_VERSION = 22 |
배포가 끝난 뒤에는 대시보드의 초록 체크만 믿지 않고 직접 확인했다.
B=https://<프로젝트>.pages.dev
curl -s -o /dev/null -w '%{http_code}\n' $B/ # 200
curl -s $B/ | grep -o '<link rel="canonical"[^>]*>' # canonical 주소
curl -s -o /dev/null -w '%{http_code}\n' $B/nope-xyz/ # 404
curl -s $B/ads.txt
이 확인에서 canonical이 엉뚱한 주소를 가리키는 문제를 하나 더 찾았는데, 그건 모노레포 배포 글에 적었다.
Worker로도 정적 사이트를 올릴 수 있다. 빌드 명령을 넣고 wrangler deploy에 결과물 폴더를 지정하는 방법인데, 나는 시도하지 않았다. 기존 사이트들이 전부 Pages여서 같은 방식으로 맞추는 쪽을 골랐다.