클라우드플레어(Cloudflare) Pages 사용법, 배포부터 접속까지 직접 해 보니

이미 Cloudflare 계정에 로그인된 맥(darwin arm64)에서 index.html 한 장이 든 새 폴더를 wrangler로 cloudflare pages에 한 번 배포했을 때, 배포 명령은 6.1초 걸렸습니다. 배포가 끝난 뒤 <프로젝트>.pages.dev 주소가 200으로 응답하기까지는 0.8초가 더 걸렸죠. 클라우드플레어 계정에 이미 로그인돼 있다면 프로젝트 만들기부터 접속 확인, 삭제까지 명령 여섯 줄로 끝납니다. AI 코딩 도구로 만든 정적 결과물을 빨리 공개 주소에 올려 보고 싶다면 아래 순서를 그대로 따라 해 보세요.

따라 할 순서와 열릴 때까지 걸린 시간

먼저 전체 순서와 단계마다 걸린 시간부터 보겠습니다. 측정 환경은 맥(darwin arm64) 한 대, wrangler 4.140.0, Node.js v22.23.1이고, 단계마다 명령을 한 번씩만 실행했습니다.

여섯 단계 모두 종료 코드 0으로 끝났습니다. 시간이 가장 많이 든 곳은 프로젝트 만들기와 배포 두 단계였고, 나머지는 1초 안팎이었어요.

도식출처: 명령 실행 실측

그렇다면 배포가 끝났다는 메시지가 뜬 직후 바로 주소를 열어도 될까요? 이번 측정에서는 주소를 5초마다 다시 묻도록 해 두었는데, 0.8초 만에 200이 돌아왔습니다. 다만 한 번 실행한 결과라서 늘 이만큼 빠르다고 단정할 수는 없습니다.

함께 읽을 글

• GitHub Pages 사용법, 무료 배포부터 접속까지 직접 해 보니
• 올라마(Ollama) 로컬 AI 사용법, 맥에서 직접 돌려 보니
• 클로드 코드(Claude Code) 플러그인 사용법, 만들기부터 첫 실행까지

단계별 명령과 출력

이제 각 단계에서 실제로 입력한 명령과 나온 출력을 순서대로 보겠습니다. 프로젝트 이름은 <프로젝트>로 바꿔 적었으니 자기 이름으로 바꿔 넣으면 됩니다.

1. 도구 버전 확인. Node.js와 wrangler가 설치돼 있는지 확인합니다.

$ node --version && wrangler --version
v22.23.1
4.140.0

2. 페이지 파일 만들기. public 폴더를 만들고 HTML 한 장을 넣습니다. AI 도구가 만든 빌드 결과 폴더가 있다면 이 단계 대신 그 폴더를 쓰면 됩니다.

$ mkdir public && printf '<!doctype html>\n<html lang="ko"><head><meta charset="utf-8"><title>Cloudflare Pages 테스트</title></head>\n<body><h1>Cloudflare Pages 테스트 페이지</h1></body></html>\n' > public/index.html && ls public
index.html

3. Pages 프로젝트 만들기. 프로덕션 브랜치를 main으로 지정해 빈 프로젝트를 만듭니다.

$ wrangler pages project create <프로젝트> --production-branch main
⛅️ wrangler 4.140.0 (update available 4.152.0)
───────────────────────────────────────────────
✨ Successfully created the '<프로젝트>' project. It will be available at https://<프로젝트>.pages.dev/ once you create your first deployment.
To deploy a folder of assets, run 'wrangler pages deploy [directory]'.

4. 폴더 올려 배포하기. 파일 한 장 업로드에 1.58 sec가 걸렸다고 출력됩니다.

$ wrangler pages deploy public --project-name <프로젝트> --branch main
⛅️ wrangler 4.140.0 (update available 4.152.0)
───────────────────────────────────────────────
Uploading... (0/1)
Uploading... (1/1)
✨ Success! Uploaded 1 files (1.58 sec)

🌎 Deploying...
✨ Deployment complete! Take a peek over at https://d48aced5.<프로젝트>.pages.dev

5. 주소로 접속해 보기. 출력에 나온 배포별 주소가 아니라 프로젝트 주소로 확인합니다.

$ curl -s https://<프로젝트>.pages.dev/
<!doctype html>
<html lang="ko"><head><meta charset="utf-8"><title>Cloudflare Pages 테스트</title></head>
<body><h1>Cloudflare Pages 테스트 페이지</h1></body></html>

6. 테스트 프로젝트 지우기. 확인만 하려던 프로젝트라면 바로 지워 둡니다.

$ wrangler pages project delete <프로젝트> --yes
⛅️ wrangler 4.140.0 (update available 4.152.0)
───────────────────────────────────────────────
Deleting <프로젝트>
Successfully deleted <프로젝트>

여기서 눈여겨볼 점이 있습니다. 배포 출력에는 d48aced5.가 앞에 붙은 배포별 주소가 나오지만, 접속 확인은 <프로젝트>.pages.dev로 했다는 점이죠. 공식 문서도 프로덕션 배포는 <PROJECT_NAME>.pages.dev에서 열린다고 설명합니다.

wrangler를 전역으로 설치하지 않았다면 어떻게 할까요? Direct Upload 문서는 npx를 붙인 형태로 안내합니다. 이 측정에서는 다른 프로젝트에 npm으로 설치돼 있던 wrangler를 그대로 썼습니다.

npx wrangler pages project create

npx wrangler pages deploy <BUILD_OUTPUT_DIRECTORY>

문서에 따르면 이름을 붙이지 않고 실행하면 프로젝트 이름과 프로덕션 브랜치를 묻습니다. 입력한 값은 node_modules/.cache/wrangler 폴더에 저장돼 다음 배포에 다시 쓰이죠. 에이전트에게 배포를 맡긴다면 이번 측정처럼 이름과 브랜치를 옵션으로 넘겨 묻는 단계를 없애는 쪽이 다루기 쉽습니다. 프로젝트 목록이 필요할 때는 --json을 붙이면 스크립트에서 읽기 좋은 형태로 받을 수 있습니다.

npx wrangler pages project list --json

폴더 업로드와 GitHub 연동, 무엇이 다를까요?

위 절차는 폴더를 직접 올리는 Direct Upload 방식입니다. 그런데 푸시할 때마다 자동으로 배포되게 하고 싶다면 Git 연동 문서의 방식을 골라야 합니다. 둘은 처음 고를 때 신중해야 하는데, 한쪽을 고르면 나중에 다른 쪽으로 바꿀 수 없기 때문이에요.

Git 연동 프로젝트라도 모든 브랜치에서 자동 배포를 끄면 wrangler로 직접 배포할 수 있다고 문서는 설명합니다. 반대로 Direct Upload 프로젝트에서 자동 배포를 쓰려면 Git 연동으로 새 프로젝트를 만들어야 하죠. 그래서 지금은 결과물만 빨리 띄워 보고 나중에 저장소 연동을 고민한다면, 이번처럼 테스트 프로젝트로 먼저 해 보고 지우는 쪽이 부담이 적습니다.

도식출처: 근거를 바탕으로 코드가 그린 도식

빌드 도구 없이 HTML만 있는 사이트도 Git 연동으로 올릴 수 있습니다. 문서는 프레임워크가 필요 없다고 밝히고, 빌드 단계가 없으면 빌드 명령 칸을 비워 두라고 안내합니다.

업로드 방식별 파일 수·크기 한도

무료로 쓸 수 있는지 궁금할 텐데요, 이번에 참고한 두 공식 문서에는 요금제 조건이 따로 적혀 있지 않습니다. 대신 업로드 방식별 한도는 분명히 나와 있으니 결과물이 큰 프로젝트라면 이것부터 확인해 보세요.

wrangler는 폴더 하나만 받고 zip 파일은 지원하지 않습니다. 대시보드의 드래그 앤 드롭은 zip 파일과 폴더를 모두 받지만, functions 폴더(Pages Functions)를 함께 배포하려면 wrangler를 써야 해요.

자주 하는 실수

• zip으로 묶어 wrangler에 넘기기. wrangler는 폴더만 받습니다. 압축하지 말고 빌드 출력 폴더를 그대로 넘기세요.
• Git 저장소 밖에서 브랜치 빼먹기. Git 작업 공간이면 wrangler가 브랜치 정보를 알아서 가져오지만, 아니면 직접 지정해야 합니다. 이번 측정에서 --branch main을 붙인 이유도 이 때문이죠.
• 프로젝트 폴더 밖에서 배포하기. 문서는 배포 전에 프로젝트 안에 있는지 확인하고, 아니면 경로를 넘기라고 안내합니다.
• 첫 배포 직후 DNS 오류에 당황하기. Git 연동 문서는 DNS가 아직 퍼지지 않았을 수 있다며, 기다리거나 다른 기기·네트워크로 확인해 보라고 합니다.
• 사용자 도메인이 붙은 프로젝트를 바로 지우기. CNAME 레코드를 먼저 지우지 않으면 없는 프로젝트를 가리키는 DNS 레코드가 남을 수 있습니다. *.pages.dev 주소만 쓰는 프로젝트는 설정에서 바로 지워도 됩니다.

배포 전에 점검할 것

• 빌드 결과물이 폴더 하나에 들어 있는가
• 파일 수와 크기가 위 한도 안인가
• 자동 배포가 필요한지 정했는가(Direct Upload와 Git 연동은 서로 바꿀 수 없음)
• 배포 뒤 <프로젝트>.pages.dev로 접속해 내용이 맞는지 확인했는가
• 테스트용 프로젝트를 지웠는가

측정 조건과 한계

이번 수치는 맥 한 대에서, 이미 클라우드플레어 계정에 로그인된 wrangler 4.140.0으로, HTML 파일 한 장을 한 번 배포해 얻은 값입니다. 실행 중 4.152.0으로 업데이트할 수 있다는 안내가 떴지만 버전은 올리지 않았습니다.

그래서 배포 6.1초, 열릴 때까지 0.8초라는 값은 다른 시간대나 파일 수가 많은 프로젝트에서는 달라질 수 있습니다. 한 번만 잰 값이라 어느 단계가 왜 오래 걸렸는지도 이 측정만으로는 가를 수 없어요. 자기 프로젝트의 실제 시간을 알고 싶다면, 같은 명령을 빌드 결과 폴더로 몇 번 반복해 단계별 시간을 직접 재 보는 방법이 가장 확실합니다.