GitHub + Cloudflare Pages로 Astro 블로그 무료 배포하기 — 자동 배포·커스텀 도메인·HTTPS까지 (2026)
Astro 블로그를 GitHub 저장소와 Cloudflare Pages로 무료 배포하는 가장 빠른 방법을 단계별로 정리했습니다. 저장소 푸시, 빌드 설정, 커스텀 도메인 연결, HTTPS, 자동 재배포까지 한 번에 끝내는 실전 가이드입니다.
블로그를 다 만들었다면, 이제 세상에 공개할 차례입니다. Astro 블로그는 정적 사이트라서 사실상 어느 호스팅이든 올릴 수 있지만, 트래픽 무제한·전 세계 CDN·자동 HTTPS가 모두 무료인 조합은 단 하나, GitHub + Cloudflare Pages 입니다.
이 글은 Astro 블로그를 GitHub에 올리고, Cloudflare Pages에 연결하고, 커스텀 도메인까지 붙여서 자동 배포 파이프라인을 완성하는 과정을 처음부터 끝까지 안내합니다. 명령어와 클릭 순서를 그대로 따라가면 30분 안에 첫 배포가 완료됩니다.
목차
- 왜 GitHub + Cloudflare Pages 조합인가
- 사전 준비물
- GitHub 저장소 만들고 코드 푸시하기
- Cloudflare Pages 프로젝트 생성
- 빌드 설정과 환경 변수
- 첫 배포 확인하기
- 커스텀 도메인 연결과 HTTPS
- 자동 재배포 흐름 이해
- 배포 후 SEO·성능 점검
- 자주 발생하는 오류와 해결법
- FAQ
1. 왜 GitHub + Cloudflare Pages 조합인가
호스팅을 고를 때 보통 가격, 속도, 운영 편의성을 봅니다. Astro 블로그 기준으로 세 가지를 모두 만족하는 곳은 많지 않습니다.
| 항목 | Cloudflare Pages | Vercel | Netlify | GitHub Pages |
|---|---|---|---|---|
| 무료 트래픽 | 무제한 | 100GB/월 | 100GB/월 | 100GB/월 |
| 빌드 분 수 제한 | 월 500회 | 월 6,000분 | 월 300분 | 사실상 제한 |
| 전 세계 CDN | ★★★★★ | ★★★★★ | ★★★★ | ★★★ |
| 자동 HTTPS | 무료 | 무료 | 무료 | 무료 |
| 커스텀 도메인 | 무제한 무료 | 무제한 무료 | 무제한 무료 | 1개 |
| Functions/Edge | Workers 통합 | Edge Funcs | Functions | 없음 |
요점은 단순합니다. Cloudflare Pages는 트래픽이 폭발해도 추가 비용이 없습니다. 블로그가 잘 되어 갑자기 유입이 몰려도 요금 폭탄이 없다는 뜻이며, 이는 장기 운영형 콘텐츠 블로그의 핵심 조건입니다.
2. 사전 준비물
배포를 시작하기 전에 다음이 준비되어 있어야 합니다.
- 로컬에서
npm run build가 에러 없이 성공하는 Astro 프로젝트 - GitHub 계정 (github.com)
- Cloudflare 계정 (dash.cloudflare.com)
- (선택) 연결할 커스텀 도메인 — 가비아·Namecheap·Cloudflare Registrar 등에서 구매 가능
로컬 빌드가 실패한다면 먼저 빌드부터 통과시키세요. Cloudflare 빌드 환경에서도 똑같이 실패합니다. 디버깅은 로컬이 훨씬 빠릅니다.
3. GitHub 저장소 만들고 코드 푸시하기
Cloudflare Pages는 GitHub 저장소를 읽어서 빌드합니다. 따라서 코드를 먼저 GitHub에 올려야 합니다.
3-1. 새 저장소 생성
github.com/new 에서 새 저장소를 만듭니다.
| 항목 | 권장 설정 |
|---|---|
| Repository name | my-astro-blog 등 원하는 이름 |
| Visibility | Private 또는 Public 모두 가능 |
| Initialize | 체크 해제 (빈 저장소로 생성) |
Public 이 아니어도 Cloudflare Pages는 OAuth 권한을 통해 Private 저장소도 읽을 수 있습니다.
3-2. 로컬 프로젝트 푸시
프로젝트 루트에서 다음을 실행합니다.
# Git 초기화가 안 되어 있다면
git init
git add .
git commit -m "chore: initial commit"
# GitHub 저장소 주소로 연결
git branch -M main
git remote add origin https://github.com/<USERNAME>/<REPO>.git
git push -u origin main푸시가 끝나면 GitHub 저장소 페이지에서 src/, public/, astro.config.mjs, package.json 등이 보이는지 확인합니다.
3-3. .gitignore 점검
기본 Astro 템플릿에는 적절한 .gitignore가 들어 있지만, 다음 항목이 빠져 있지 않은지 한 번 더 확인합니다.
node_modules/
dist/
.astro/
.env
.env.*
.DS_Store
.env같은 비밀 값이 저장소에 커밋되면 Cloudflare가 아니라 검색 봇이 먼저 찾아갑니다. 반드시 제외하세요.
4. Cloudflare Pages 프로젝트 생성
dash.cloudflare.com 에 로그인합니다.
- 왼쪽 메뉴에서 Workers & Pages 선택
- Create application → Pages 탭 → Connect to Git 클릭
- GitHub 연결 버튼 클릭, 권한 요청 화면에서 방금 만든 저장소만 선택해 허용
- 목록에서
my-astro-blog저장소 선택 → Begin setup
처음 연결할 때 GitHub의 Cloudflare Pages 앱 설치 화면이 뜹니다. All repositories 대신 Only select repositories 로 필요한 저장소만 허용하는 것이 안전합니다.
5. 빌드 설정과 환경 변수
Cloudflare가 자동으로 Astro를 감지하지만, 빌드 설정은 한 번 더 직접 확인하는 것이 좋습니다.
5-1. 빌드 설정 (Build configuration)
| 항목 | 값 |
|---|---|
| Framework preset | Astro |
| Build command | npm run build |
| Build output directory | dist |
| Root directory | / (기본값) |
5-2. 환경 변수 (Environment variables)
Astro는 빌드 시점에 Node 버전과 일부 시크릿이 필요합니다.
| 변수 | 값 | 용도 |
|---|---|---|
NODE_VERSION | 22 | Cloudflare 빌드 컨테이너 Node 버전 고정 |
NPM_FLAGS | --legacy-peer-deps | (필요 시) peer dep 충돌 우회 |
PUBLIC_SITE_URL | https://example.com | 사이트맵·OG에 사용할 절대 URL |
NODE_VERSION은 잊으면 가장 흔한 오류 원인입니다. Cloudflare 기본 Node 버전이 낮아Cannot find module,Unexpected token같은 빌드 실패가 발생합니다.
설정을 마치면 Save and Deploy 버튼을 누릅니다.
6. 첫 배포 확인하기
빌드 로그가 실시간으로 흘러갑니다. 일반적으로 다음 단계를 거칩니다.
Cloning repository...
Installing dependencies (npm ci)...
Running build command: npm run build
✓ 12 page(s) built
Uploading assets to Cloudflare network...
Deployment complete!성공하면 https://my-astro-blog.pages.dev 형태의 임시 도메인이 발급됩니다. 클릭해서 다음을 확인합니다.
✅ 배포 직후 점검 체크리스트
| 항목 | 확인 방법 | 정상 동작 |
|---|---|---|
| 홈 페이지 | / 접속 | 로컬과 동일한 화면 |
| 블로그 목록 | /blog 접속 | 글 목록 표시 |
| 상세 페이지 | 글 클릭 | 본문·이미지 정상 |
| 사이트맵 | /sitemap-index.xml | XML 정상 출력 |
| RSS | /rss.xml | XML 정상 출력 |
| 404 | /존재하지않는경로 접속 | 커스텀 404 또는 기본 페이지 |
이 중 하나라도 깨진다면 10번 섹션 을 먼저 확인하세요.
7. 커스텀 도메인 연결과 HTTPS
.pages.dev 도메인을 그대로 써도 동작은 하지만, SEO와 신뢰도 면에서 자기 도메인을 붙이는 편이 압도적으로 좋습니다.
7-1. 도메인 추가
Cloudflare Pages 프로젝트 화면 → Custom domains → Set up a custom domain.
- 도메인이 Cloudflare에 등록되어 있는 경우: 도메인을 입력만 하면 자동으로 DNS 레코드가 만들어집니다.
- 도메인이 외부 등록기관(가비아, Namecheap 등)에 있는 경우: 표시되는
CNAME값을 해당 등록기관 DNS 관리 화면에 추가합니다.
| 레코드 타입 | 호스트 | 값(Value) |
|---|---|---|
| CNAME | www | my-astro-blog.pages.dev |
| CNAME 또는 ALIAS | @ (루트 도메인) | my-astro-blog.pages.dev |
루트 도메인(
example.com)에 CNAME을 허용하지 않는 등록기관도 있습니다. 이 경우 Cloudflare로 도메인 네임서버를 이전하면 가장 깔끔하게 해결됩니다.
7-2. HTTPS 자동 발급
도메인이 활성화되면 Cloudflare가 Let’s Encrypt 또는 Universal SSL 인증서를 자동 발급합니다. 보통 수 분 이내에 https:// 가 활성화됩니다.
7-3. astro.config.mjs의 site 갱신
도메인을 붙였다면 site 값을 실제 도메인으로 바꿉니다.
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://example.com',
});이 값은 사이트맵·RSS·OG 절대 URL 의 기준이 됩니다. 변경 후 다시 푸시하면 자동 재배포됩니다.
8. 자동 재배포 흐름 이해
설정이 끝나면 더 이상 손댈 일이 없습니다. 흐름은 다음과 같습니다.
글 작성 (Markdown)
↓
git commit / git push
↓
GitHub Webhook → Cloudflare Pages
↓
npm ci → npm run build → 정적 산출물 업로드
↓
전 세계 CDN에 즉시 반영 (보통 30초~2분)브랜치별 동작
| 브랜치 | 동작 |
|---|---|
main (Production) | 실제 도메인에 반영 |
| 그 외 모든 브랜치 | 자동으로 프리뷰 URL 생성 (<branch>.<project>.pages.dev) |
프리뷰 URL 은 동료 리뷰나 글 사전 공유에 매우 유용합니다. 임시 도메인이라 검색 엔진 색인은 막혀 있습니다(noindex).
9. 배포 후 SEO·성능 점검
배포가 끝났다면 검색 엔진에 알리는 단계가 남았습니다.
9-1. 구글 등록
Google Search Console 에서 속성을 추가합니다.
- 도메인 속성 추가(권장) — DNS TXT 인증
- 사이트맵 제출 —
https://example.com/sitemap-index.xml - URL 검사 — 대표 글 3~5개를 색인 요청
9-2. 네이버 등록
- 사이트 등록 → HTML 메타 태그 인증
- 사이트맵 제출
- RSS 제출 —
https://example.com/rss.xml
9-3. Lighthouse 점검
Chrome DevTools → Lighthouse 탭 → Mobile + Performance/SEO/Accessibility/Best Practices 전 항목 실행. 정적 Astro 블로그라면 95점 이상이 기본값입니다. 점수가 낮다면 이미지 크기·폰트 로드 방식을 먼저 의심하세요.
10. 자주 발생하는 오류와 해결법
| 증상 | 원인 | 해결 |
|---|---|---|
error: Unsupported engine / Unexpected token | Cloudflare 기본 Node 버전이 낮음 | 환경 변수 NODE_VERSION=22 추가 |
npm ci 단계에서 실패 | package-lock.json 누락 또는 손상 | 로컬에서 npm install 후 lockfile 함께 커밋 |
Module not found: ../../assets/... | 이미지 경로 오타, 대소문자 차이 | macOS는 대소문자 무시, Cloudflare 리눅스는 대소문자 구분 |
| 빌드는 성공인데 사이트맵에 글이 없음 | astro.config.mjs의 site 미설정 | 실제 도메인을 site에 지정 |
커스텀 도메인이 DNS_PROBE_FINISHED_NXDOMAIN | DNS 전파 지연 또는 레코드 오타 | 최대 24시간 대기, dig / nslookup 으로 CNAME 값 확인 |
Mixed Content 경고 | 글 안에 http:// 이미지가 섞임 | 모든 외부 URL을 https:// 로 교체 |
| 한국에서 접속이 느림 | 자산이 큰 이미지로 묶임 | src/assets/ + <Image /> 로 자동 최적화 적용 |
| Private 저장소가 목록에 안 보임 | Cloudflare Pages 앱이 접근 권한 없음 | GitHub → Settings → Applications → Cloudflare Pages 권한 재설정 |
FAQ
Q1. Cloudflare Pages는 정말 트래픽이 무제한 무료인가요?
네. 2026년 기준 대역폭(bandwidth)과 요청 수에 별도 과금이 없습니다. 다만 빌드 횟수(월 500회 무료), 동시 빌드 수, Functions 실행 시간에는 제한이 있어 일반 블로그 운영에는 충분하지만, 빈번한 푸시는 한도를 확인해야 합니다.
Q2. Vercel·Netlify와 비교해 어떤가요?
개발자 편의성은 Vercel이 약간 앞서고, 무료 트래픽과 글로벌 CDN은 Cloudflare가 압도적입니다. 장기 운영형 블로그라면 비용 폭탄이 없는 Cloudflare가 안전한 선택입니다.
Q3. GitHub Actions 없이도 자동 배포가 되나요?
네. Cloudflare Pages가 자체적으로 GitHub Webhook을 받아 빌드합니다. 별도 워크플로 파일을 만들 필요가 없습니다. 다만 빌드 전후로 추가 검사(테스트·린트)를 돌리고 싶다면 GitHub Actions를 함께 써도 됩니다.
Q4. 글 하나 고치는 데도 매번 재배포해야 하나요?
네. 정적 사이트는 빌드 산출물이 곧 사이트이므로 글 수정 → push → 재빌드 → CDN 반영의 흐름을 거칩니다. 보통 30초~2분 안에 완료됩니다. 즉시성이 떨어진다고 느낄 수 있지만, 그 대가로 속도·안정성·보안이 극대화됩니다.
Q5. 도메인은 어디서 사는 게 좋나요?
가격과 관리 편의 모두를 생각하면 Cloudflare Registrar 가 가장 합리적입니다. 마진 없이 도매가로 판매하며, DNS 관리도 같은 대시보드에서 처리됩니다. 국내 결제가 편하다면 가비아·후이즈도 좋습니다.
Q6. 비공개 글을 운영할 수 있나요?
기본 Astro에서는 draft: true 로 빌드에서 제외하거나, Cloudflare Access 기능으로 특정 경로에 인증을 걸 수 있습니다. 다만 진짜 비공개라면 별도 저장소·노션·메모 앱을 쓰는 편이 안전합니다.
Q7. 배포 후 글 URL을 바꾸면 어떻게 되나요?
기존 URL이 깨지면서 검색 색인이 사라질 수 있습니다. 반드시 _redirects 파일에 301 리디렉션을 추가하세요.
# public/_redirects
/old-url /new-url 301요약
- GitHub 저장소 생성 → 코드 push 가 첫 단계.
- Cloudflare Pages 연결 → 빌드 명령
npm run build·출력dist만 잘 맞추면 끝. NODE_VERSION=22는 거의 모든 초기 빌드 실패의 해결책.- 커스텀 도메인 + 자동 HTTPS 까지 무료로 5분 안에 완료.
- 이후 운영은
git push한 번 으로 전 세계 CDN에 자동 반영.
Astro의 진가는 글을 쓰는 데만 집중하면 나머지는 자동으로 굴러간다는 점에 있습니다. GitHub과 Cloudflare Pages가 그 자동화의 양 축입니다. 첫 배포까지 30분, 익숙해지면 글 하나 발행에 2분이면 충분합니다. 이제 마음 편히 글에만 집중할 차례입니다.