Cloudflare Pages 배포 가이드¶

비개발자도 따라할 수 있는 무료 홈페이지 배포 방법 실제 storywinner.co.kr 배포 과정 기반 (2026-03-18)

왜 Cloudflare Pages?¶

항목	Cloudflare Pages	Vercel	비고
무료 대역폭	무제한	100GB/월	클플 압도적
빌드 시간	500회/월	6000분/월	둘 다 충분
이미지 저장소	R2 (10GB 무료)	별도 없음	R2는 전송비 0원
커스텀 도메인	무료 SSL	무료 SSL	동일
서버리스 함수	Workers	Serverless	둘 다 가능
한국 CDN	있음	있음	동일

결론: 콘텐츠 사이트 + 이미지 많으면 Cloudflare가 유리

사전 준비¶

1. 계정 만들기¶

GitHub: github.com 가입 (코드 저장소)
Cloudflare: dash.cloudflare.com 가입 (배포 플랫폼)

2. 도구 설치 (한 번만)¶

# Node.js 설치 (nodejs.org에서 LTS 버전)
# 설치 확인
node -v
npm -v

# GitHub CLI 설치 (선택, 터미널에서 편하게 쓰려면)
# https://cli.github.com/ 에서 다운로드
gh auth login

배포 과정 (5단계)¶

1단계: 프로젝트 만들기 (Astro 예시)¶

# 새 프로젝트 생성
npm create astro@latest my-site
cd my-site
npm install

# 로컬에서 확인
npm run dev
# 브라우저에서 http://localhost:4321 열기

2단계: GitHub에 올리기¶

# Git 초기화 (이미 되어 있으면 건너뛰기)
git init
git add .
git commit -m "첫 커밋"

# GitHub에 비공개 리포 만들고 push
gh repo create 내계정/my-site --private --source=. --remote=origin --push

GitHub 웹에서도 가능: 1. github.com → New repository 2. 이름 입력, Private 선택 3. 터미널에서 push

3단계: Cloudflare Pages 연결¶

dash.cloudflare.com 로그인
왼쪽 메뉴: Compute > Workers & Pages
Create application 클릭
화면 맨 아래: "Looking to deploy Pages? Get started" 클릭 (중요!)
바로 보이는 건 Worker 생성이라 다름!
Continue with GitHub 클릭
GitHub 계정 연결 승인
리포지토리 선택 (my-site)

4단계: 빌드 설정¶

항목	값
Project name	my-site (URL이 됨: my-site.pages.dev)
Production branch	master (또는 main)
Framework preset	Astro (드롭다운에서 선택)
Build command	`npm run build`
Build output directory	`dist`

Save and Deploy 클릭!

5단계: 배포 확인¶

1~2분 후 "Success!" 화면
URL: my-site.pages.dev 에서 확인
이후 GitHub에 push할 때마다 자동 배포됨

자동 배포 흐름¶

코드 수정 → git commit → git push → Cloudflare가 자동 빌드 → 1~2분 후 반영

push만 하면 끝. 빌드 서버를 관리할 필요 없음.

커스텀 도메인 연결¶

Cloudflare에 도메인 추가¶

Pages 프로젝트 > Custom domains > Set up a custom domain
storywinner.co.kr 입력
Cloudflare가 네임서버 2개를 알려줌

도메인 업체에서 네임서버 변경¶

도메인 관리 사이트 로그인 (예: 아이티이지, 가비아 등)
네임서버를 Cloudflare가 알려준 것으로 변경
24~48시간 내 적용 (보통 몇 시간)

확인¶

storywinner.co.kr 접속 시 사이트 보이면 완료
HTTPS(SSL)는 Cloudflare가 자동 발급

서브도메인 연결 (같은 Cloudflare 계정일 때)¶

예: intro.medinterior.com → Cloudflare Pages 프로젝트에 연결

방법 (30초면 끝): 1. Workers & Pages > 해당 프로젝트 선택 2. Custom domains 탭 클릭 3. 서브도메인 입력 (예: intro.medinterior.com) 4. Activate domain 클릭

자동으로 되는 것: - CNAME 레코드 자동 생성 (같은 클플 계정이라서) - SSL 인증서 자동 발급 - 비용 0원

주의: - 도메인의 DNS가 이미 Cloudflare에 있어야 함 (네임서버 이전 완료 상태) - 다른 DNS(가비아, 카페24 등)에 있으면 CNAME을 직접 추가해야 함 - 카카오맵 등 도메인 기반 API 쓸 때, 개발자 콘솔에 새 서브도메인도 등록 필요

실전 예시: - intro.medinterior.com → woori-intro Pages 프로젝트 (2026-03-27 연결 완료)

Cloudflare R2 (이미지 저장소)¶

왜 R2?¶

이미지를 git에 넣으면 리포가 무거워짐
R2는 10GB 무료, 전송비 0원
CDN이 자동 적용돼서 빠름

R2 버킷 만들기¶

Cloudflare 대시보드 > Storage & databases > R2
Create bucket > 이름 입력 (예: my-site-assets)
Settings > Public access 활성화
Public URL 확인 (예: https://pub-xxx.r2.dev)

이미지 업로드¶

# wrangler CLI로 업로드
npx wrangler r2 object put my-site-assets/images/photo.jpg --file=./photo.jpg

# 또는 Cloudflare 대시보드에서 직접 업로드 (드래그 앤 드롭)

HTML에서 사용¶

<img src="https://pub-xxx.r2.dev/images/photo.jpg" alt="설명" />

트러블슈팅¶

빌드 실패 시¶

Pages 대시보드 > View build logs 클릭
에러 메시지 확인
로컬에서 npm run build 먼저 테스트

자주 겪는 에러¶

에러	해결
`Cannot find module`	`npm install` 후 다시 push
`Build output directory not found`	Build output이 `dist`인지 확인
Node.js 버전 문제	Environment variables에서 `NODE_VERSION=18` 추가

Environment Variables 설정¶

Pages 대시보드 > Settings > Environment variables - NODE_VERSION: 18 (또는 20)

실전 예시: storywinner.co.kr 배포¶

기술 스택: Astro 6 + Tailwind CSS v4
GitHub: hangglwriter/storywinner (private)
Cloudflare Pages: storywinner.pages.dev
R2 버킷: storywinner-assets
도메인: storywinner.co.kr (아이티이지에서 관리, 네임서버만 변경)

배포 설정¶

Framework: Astro
Build command: npm run build
Output: dist
Branch: master

비용: 0원¶

Cloudflare Pages: 무료
R2 10GB: 무료
도메인: 연 1.5만원 (기존 보유)

Vercel과 비교 (강의용 참고)¶

Vercel이 더 나은 경우¶

Next.js 사용 시 (Vercel이 만든 프레임워크)
ISR(증분 정적 생성) 필요 시
빠르게 시작하고 싶을 때 (설정이 더 간단)

Cloudflare가 더 나은 경우¶

이미지가 많은 콘텐츠 사이트 (R2 연동)
대역폭 제한 걱정 없이 쓰고 싶을 때
Workers 등 서버리스 기능 활용 시
도메인을 이미 Cloudflare에서 관리 중일 때

둘 다 쓰는 경우 (실제 운영)¶

youtube-reports → Vercel (간단한 정적 사이트)
storywinner → Cloudflare (이미지 많은 콘텐츠 사이트)