정적 웹사이트 클라우드플레어 페이지 배포 방법
핵심 결론 및 주요 쟁점 요약
Cloudflare Pages는 정적 웹사이트를 빠르고 간편하게 글로벌 CDN에 무료로 배포할 수 있는 최고의 솔루션 중 하나입니다. 무료 플랜에서도 월 500회 배포와 무제한 대역폭을 제공하여 Vercel, Netlify의 강력한 대안으로 꼽힙니다.
배포 방식은 크게 ①Git 연동 자동화, ②Direct Upload(드래그 앤 드롭), ③Wrangler CLI 세 가지로 나뉘며, Vue, React, Next.js 등 30개 이상의 주요 프레임워크 빌드를 자체 지원합니다.
💡 플랫폼 개요
Cloudflare Pages는 HTML/CSS/JS 및 JAMstack 기반 웹 애플리케이션을 인터넷에 쉽게 띄우는 PaaS 플랫폼입니다. 가장 큰 장점은 Cloudflare 특유의 전 세계 분산 네트워크(CDN) 위에서 동작해 로딩 속도가 비약적으로 빠르다는 점입니다. 단순 정적 페이지뿐만 아니라 'Pages Functions'를 추가하면 서버리스 API 함수까지 운용 가능합니다.
배포 방식 3가지 비교
자신의 개발 환경과 규모에 맞춰 배포 방식을 선택할 수 있습니다.
| 배포 방식 | 장점 | 단점 및 제한 | 추천 대상 |
|---|---|---|---|
| Git 연동 | GitHub에 코드 push 시 자동 배포 (CI/CD) | Git 저장소가 필수로 요구됨 | 팀 협업 프로젝트, 자동화 선호 |
| Wrangler CLI | CLI 상에서 초고속 배포, Github Actions 조합 | Node.js/npm 지식 필요 | 자체 커스텀 빌드 구성 시 |
| 드래그 앤 드롭 | Git이나 코드 지식 없이 폴더째 올려 끝냄 | 최대 파일 1,000개, 25MB 이하 제한 | 랜딩 페이지, 단발성 포트폴리오 |
방법 1: Git 연동 배포 (가장 추천!)
GitHub나 GitLab에 코드를 올릴 때마다 알아서 빌드되고 배포되는 가장 우수한 방식입니다.
- Cloudflare 대시보드 접속 → 좌측 메뉴 [Workers & Pages] 선택
- [Create application] → [Pages] 탭 → [Connect to Git] 클릭
- 본인의 GitHub(또는 GitLab) 계정을 로그인해 연동 권한 승인
- 배포할 저장소(Repository) 레포지토리 선택
- [Begin setup] 버튼을 눌러 본격적인 배포 설정 진입
- 프로젝트 이름 지정 (이 이름으로 URL 생성:
이름.pages.dev) - Production branch 지정 (
main또는master등 메인 브랜치 설정) - Build command(빌드 명령어)와 Build output directory(결과물 폴더) 지정
- [Save and Deploy]를 누르면 자동으로 빌드 로그가 올라가며 사이트가 배포됩니다!
(팁: 메인 브랜치 외의 브랜치(dev 등)에 push를 하면 해당 브랜치명을 딴 '프리뷰 URL'이 임시로 생성되어 미리 테스트해 볼 수 있습니다.)
방법 2: Wrangler CLI 배포
개발자들에게 매우 친숙한 터미널 툴을 이용하는 방식입니다.
# 1. Wrangler 전역 설치
npm install -g wrangler
# 2. 터미널 탭에서 Cloudflare 로그인 (브라우저로 리다이렉트 됨)
wrangler login
# 3. 신규 프로젝트 공간 생성 (처음 한 번만)
wrangler pages project create 나의프로젝트명
# 4. 빌드가 끝난 dist 폴더를 지정해 배포 (가장 잦은 명령어)
wrangler pages deploy ./dist
# 5. 프로덕션이 아닌 프리뷰 채널용으로 배포 테스트
wrangler pages deploy ./dist --branch=preview
방법 3: 드래그 앤 드롭 방식 (노코드)
코드, 패키지, Git 뭐든 모르겠고 당장 화면만 띄워야 할 때 씁니다.
- 대시보드 → [Workers & Pages] → [Create application] 클릭
- 탭에서 [Drag and drop your files] 선택
- 프로젝트 이름 입력 후, 컴퓨터에 있는
dist또는build결과물 폴더(ZIP도 가능)를 냅다 던져 넣습니다. - Deploy site 클릭 시 3초 만에 업로드가 끝납니다.
🛠️ 자주 쓰는 프레임워크별 빌드 룰 세팅
Cloudflare 대시보드는 거의 모든 프레임워크의 빌드 설정을 자동(Preset)으로 잡아주지만, 수동으로 입력해야 할 때가 있습니다. 아래 표는 대표적인 출력 디렉토리 기본값입니다.
| 사용 프레임워크 | 빌드 명령어(Build command) | 출력 디렉토리(Output directory) |
|---|---|---|
| React (Vite) / Vue | npm run build | dist |
| Svelte | npm run build | public |
| Next.js (정적 내보내기) | npx next build | out |
| Nuxt.js / Astro | npm run build | dist |
| Jekyll | jekyll build | _site |
| 바닐라 HTML/JS | (빈칸으로 둡니다) | (폴더를 통째로 지정하거나 빈칸) |
환경 변수(Environment Variables) 설정 팁
API KEY나 DB 주소 같은 민감 정보는 코드에 하드코딩하지 않고 환경 변수로 주입합니다. Cloudflare Pages 셋팅 탭에서 손쉽게 추가 가능합니다.
알아두면 좋은 점은, 구형 레거시 버전을 돌려야 할 경우 환경변수 설정에 NODE_VERSION 이란 키워드로 특정 버전 번호를 입력해 빌드 환경의 노드 버전을 강제할 수 있다는 점입니다.
커스텀 도메인 연결 연결
기본적으로 제공되는 주소(~.pages.dev)가 마음에 들지 않아 나만의 유료 도메인을 연결하고 싶을 땐, 프로젝트 세팅의 [Custom domains] 탭에 진입합니다. Cloudflare에서 네임서버를 관리 중인 도메인이라면 버튼 클릭 2번 만에 DNS 연동 및 SSL(HTTPS) 인증서가 무료로 발급·적용됩니다.
🔍 실무를 위한 숨은 맥락 (주의사항)
- 무료 버전에 대한 환상 주의: 배포 횟수는 월 500회입니다. 넉넉하지만 CI 봇을 너무 촘촘하게 짜서 커밋마다 배포하게 두면 은근 500회 벽에 자주 부딪힙니다.
- 모노레포(Monorepo)의 경우: 저장소 안에 프론트엔드와 백엔드 폴더가 공존한다면, 설정할 때 꼭 Root directory 공간에 프론트엔드가 있는 하위 경로 폴더를 써줘야 정상 빌드됩니다.
- Next.js 사용자 주의점: Vercel 자사 서비스가 아니다 보니
@cloudflare/next-on-pages어댑터를 추가 설치해야 돌아가는 제약이 있고, Next.js의 모든 렌더링 기능을 100% 지원하진 않습니다(Edge Runtime 기반만 호환). - 에러 났을 땐 롤백: 대시보드 배포 히스토리에 들어가서 이전 정상 작동 버전 우측의 롤백 버튼을 누르면 다운타임 없이 1초 만에 롤백됩니다.