Astro Cloudflare Pages 배포 가이드: GitHub 자동 배포까지

왜 Cloudflare Pages를 선택했는가

Astro 사이트는 정적 배포와 궁합이 좋습니다.
Cloudflare Pages는 설정이 단순하고, 전 세계 엣지 네트워크를 바로 사용할 수 있어 작은 사이트부터 포트폴리오, 블로그, 도구 소개 페이지까지 운영하기 수월합니다.

장점은 명확합니다.

• GitHub와 연결하면 push만으로 자동 배포
• 기본 *.pages.dev 도메인 즉시 제공
• 커스텀 도메인 연결이 쉬움
• 정적 사이트 기준으로 설정이 단순함

빠르게 훑고 바로 배포하고 싶다면 아래 순서만 따라가면 됩니다.

1. 로컬에서 pnpm build 확인
2. GitHub 저장소에 푸시
3. Cloudflare Pages에서 저장소 연결
4. Astro / pnpm build / dist 설정 적용
5. *.pages.dev 확인 후 커스텀 도메인 연결

기본 전제

이 글은 아래 기준으로 설명합니다.

• Astro 프로젝트가 이미 있거나 새로 만들 예정
• GitHub 저장소를 사용할 예정
• 정적 출력(output: "static") 기준

1. Astro 프로젝트 준비

새 프로젝트를 만드는 경우:

pnpm create astro@latest my-site
cd my-site
pnpm install

정적 사이트라면 특별한 어댑터 없이도 배포할 수 있습니다.

로컬 빌드 확인:

pnpm build

빌드 후 dist/ 폴더가 정상 생성되면 준비는 끝입니다.

2. GitHub 저장소 연결

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<username>/<repo>.git
git push -u origin main

Cloudflare Pages는 이 저장소를 기준으로 자동 배포를 수행합니다.

3. Cloudflare Pages에서 프로젝트 생성

Cloudflare 대시보드에서:

1. Workers & Pages 또는 Pages 메뉴 진입
2. Create application
3. Pages
4. Connect to Git
5. GitHub 저장소 선택

그 다음 빌드 설정을 아래처럼 맞추면 됩니다.

• Framework preset: Astro
• Build command: pnpm build
• Build output directory: dist

Node 버전을 명시하고 싶다면 환경 변수에 다음 값을 넣으면 됩니다.

NODE_VERSION=20

4. 첫 배포 확인

설정 후 배포를 시작하면 Cloudflare가 자동으로 빌드 로그를 보여줍니다.

정상 완료되면 다음 형태의 주소가 발급됩니다.

https://<project-name>.pages.dev

이 단계에서 먼저 기본 주소로 접속이 되는지 확인하는 것이 좋습니다.

5. 커스텀 도메인 연결

운영 도메인을 붙일 때는 Pages 프로젝트에서 Custom domains로 들어가 원하는 서브도메인을 연결하면 됩니다.

예:

• tools.example.com
• blog.example.com
• koreastreamer.com

Cloudflare DNS를 같이 쓰고 있다면 연결 과정이 훨씬 단순합니다.

6. 이후 운영 방식

이후부터는 별도 수동 업로드가 필요 없습니다.

git add .
git commit -m "Update content"
git push origin main

이렇게만 해도 Pages가 자동으로 새 빌드를 만들고 배포합니다.

브랜치 기반 Preview도 쓸 수 있어서, 본 배포 전에 미리 링크로 확인하기 좋습니다.

운영하면서 느낀 포인트

Cloudflare Pages의 강점은 “화려한 기능”보다 “운영 피로도가 낮다”는 점입니다.

• 정적 사이트 배포가 빠름
• DNS와 같이 쓰면 관리 포인트가 줄어듦
• 문서 사이트, 소개 페이지, 개인 블로그와 궁합이 좋음

Astro처럼 정적 생성 기반이 강한 도구와 붙이면 특히 편합니다.

마무리

Astro 사이트를 빠르고 안정적으로 배포하려면 Cloudflare Pages가 실용적인 선택입니다.

복잡한 서버 운영 없이도:

• GitHub 연동
• 자동 배포
• 커스텀 도메인
• 빠른 전송

까지 한 번에 가져갈 수 있습니다.

관련 글

• OBS 오버레이를 React로 만드는 방법
• KillKagi 개발기