Cloudflare Pages로 개인 홈페이지를 무료 배포한 과정
GitHub 저장소 준비부터 Cloudflare Pages 연결, 빌드 설정, 자동 배포, 사용자 도메인 연결까지 개인 홈페이지를 무료로 공개하는 과정을 정리했습니다.
Cloudflare Pages로 개인 홈페이지를 무료 배포한 과정
개인 홈페이지를 만들고도 배포 비용과 서버 관리가 부담되어 로컬에만 두는 경우가 많습니다. 저도 별도의 서버를 계속 관리하기보다는, GitHub에 코드를 올리면 자동으로 배포되고 HTTPS까지 적용되는 단순한 구조를 원했습니다. 정적 HTML·CSS·JavaScript로 만든 홈페이지라면 Cloudflare Pages가 이 조건에 잘 맞았습니다.
이 글은 GitHub 저장소를 준비하고 Cloudflare Pages에 연결한 뒤, 기본 주소와 사용자 도메인으로 사이트를 공개하는 전체 과정을 정리한 기록입니다. 프레임워크 없이 만든 정적 사이트를 기준으로 설명하지만 React, Vite, Astro 같은 도구도 빌드 명령과 출력 폴더만 맞추면 흐름은 같습니다.
1. 배포 전에 준비한 것
먼저 다음 세 가지를 준비했습니다.
• Cloudflare 계정
• GitHub 계정과 홈페이지 저장소
• 첫 화면으로 사용할 index.html 파일
정적 사이트의 최소 구조는 아주 단순합니다. 저장소 최상위에 index.html이 있고, 필요하면 style.css와 app.js를 함께 둡니다. 로컬에서 index.html을 열어 화면과 링크가 정상적으로 동작하는지 먼저 확인했습니다. 이미지 경로는 컴퓨터의 절대 경로가 아니라 ./images/photo.webp처럼 저장소 안에서 찾을 수 있는 상대 경로를 사용해야 합니다.
배포 전에는 API 키, 비밀번호, 개인 설정 파일이 저장소에 들어가지 않았는지도 확인했습니다. 한 번 공개 저장소에 올라간 비밀값은 파일을 삭제해도 Git 기록에 남을 수 있으므로, 민감한 값은 처음부터 환경 변수나 Cloudflare의 비밀값 설정으로 분리하는 편이 안전합니다.
2. GitHub 저장소에 홈페이지 올리기
새 저장소를 만들고 홈페이지 파일을 커밋한 다음 main 브랜치에 올렸습니다. Cloudflare Pages의 Git 연동은 GitHub와 GitLab을 지원하며, 저장소에 변경사항을 푸시할 때마다 자동으로 빌드하고 배포할 수 있습니다. 공개 저장소뿐 아니라 비공개 저장소도 연결할 수 있습니다.
여기서 중요한 점은 Cloudflare가 선택한 저장소에 접근할 수 있도록 권한을 허용하는 것입니다. 모든 저장소에 대한 권한을 줄 필요 없이 배포할 저장소만 선택할 수 있다면 그 범위만 허용하는 편이 좋습니다.
3. Cloudflare Pages 프로젝트 만들기
Cloudflare 대시보드에서 Workers & Pages로 이동한 뒤 새 애플리케이션 생성, Pages, Git 연결 순서로 진행했습니다. GitHub 계정을 연결하고 앞에서 만든 저장소를 선택했습니다.
프로젝트 설정에서 확인할 항목은 다음과 같습니다.
• 프로젝트 이름: 기본 pages.dev 주소에 사용됩니다.
• 프로덕션 브랜치: 일반적으로 main을 선택합니다.
• 프레임워크 프리셋: 순수 HTML 사이트라면 프레임워크 없음을 선택합니다.
• 빌드 명령: 빌드 과정이 없는 정적 사이트라면 비워둘 수 있습니다.
• 빌드 출력 디렉터리: 실제 공개할 파일이 들어 있는 폴더를 지정합니다.
Vite처럼 빌드가 필요한 프로젝트라면 빌드 명령은 npm run build, 출력 디렉터리는 보통 dist입니다. 설정값은 프로젝트마다 다르므로 package.json과 해당 프레임워크 문서를 함께 확인해야 합니다. 저장소 전체가 사이트 파일이라면 루트 디렉터리를 바꿀 필요가 없지만, 모노레포라면 홈페이지가 들어 있는 하위 경로를 루트 디렉터리로 지정해야 합니다.
4. 첫 배포와 오류 확인
설정을 저장하면 Cloudflare가 저장소를 내려받고, 필요한 경우 의존성을 설치한 다음 사이트를 배포합니다. 성공하면 프로젝트명.pages.dev 형태의 주소가 만들어집니다.
첫 배포 후에는 첫 화면만 보고 끝내지 않고 다음 항목을 확인했습니다.
1. 직접 입력한 하위 페이지 주소가 열리는지
2. CSS, JavaScript, 이미지가 모두 로드되는지
3. 모바일 화면에서 메뉴와 글자가 깨지지 않는지
4. 브라우저 주소창에 HTTPS가 적용되었는지
5. 존재하지 않는 주소의 동작이 의도한 방식인지
배포가 실패하면 Deployments 화면의 빌드 로그를 먼저 보는 것이 가장 빠릅니다. 자주 생기는 원인은 잘못된 출력 폴더, Node.js 버전 차이, 대소문자가 다른 파일명, 저장소에 포함되지 않은 이미지입니다. 특히 macOS에서는 정상처럼 보이던 파일명 대소문자 차이가 배포 환경에서 문제를 만들 수 있습니다.
5. 코드를 수정하면 자동으로 다시 배포됩니다
Git 연동의 가장 편한 점은 이후 작업입니다. 로컬에서 수정하고 main 브랜치에 푸시하면 Cloudflare Pages가 새 배포를 자동으로 시작합니다. 별도로 파일을 FTP로 올리거나 서버에 접속할 필요가 없습니다.
또한 다른 브랜치나 Pull Request의 변경사항은 미리보기 배포로 확인할 수 있습니다. 운영 주소를 바로 바꾸기 전에 실제 웹 환경에서 레이아웃과 기능을 확인할 수 있어 안전합니다. 문제가 생기면 이전 배포 기록을 비교할 수 있다는 점도 개인 사이트 운영에 유용했습니다.
6. 사용자 도메인 연결하기
기본 pages.dev 주소만으로도 사이트를 사용할 수 있지만, 개인 홈페이지답게 보이도록 보유한 도메인을 연결할 수 있습니다. Pages 프로젝트의 Custom domains에서 도메인을 추가하고 안내되는 DNS 설정을 적용하면 됩니다.
도메인의 DNS를 Cloudflare에서 관리하고 있다면 연결 과정이 비교적 간단합니다. 다른 업체에서 DNS를 관리한다면 Cloudflare가 안내하는 CNAME 등의 레코드를 정확하게 추가해야 합니다. DNS 변경은 즉시 보일 때도 있지만 전파에 시간이 걸릴 수 있습니다. 연결 후에는 www 주소와 루트 도메인 중 어느 쪽을 대표 주소로 사용할지 정하고, 다른 주소는 대표 주소로 이동시키는 것이 좋습니다.
7. 무료이지만 한계는 확인해야 합니다
Cloudflare Pages 무료 플랜은 개인 정적 홈페이지에 넉넉한 편이지만 무제한은 아닙니다. 공식 문서 기준으로 무료 플랜의 빌드는 월 500회이고, 한 사이트에 최대 20,000개 파일을 둘 수 있으며, 정적 파일 하나의 최대 크기는 25MiB입니다. Pages Functions를 사용하면 요청량이 Workers 플랜의 사용량에 포함됩니다.
따라서 사진과 동영상을 원본 크기로 무작정 올리기보다는 이미지를 WebP 등으로 최적화하고, 큰 파일이나 많은 미디어가 필요하면 별도 저장소 사용을 검토하는 것이 좋습니다. 정적 페이지 배포는 무료여도 도메인 구매 비용은 별개라는 점도 기억해야 합니다. 무료 한도가 정책에 따라 바뀔 수 있으므로 실제 운영 전에는 공식 Limits 문서를 다시 확인하는 것이 안전합니다.
마무리
Cloudflare Pages를 사용하면서 가장 편했던 점은 서버를 직접 관리하지 않아도 된다는 것이었습니다. GitHub에 변경사항을 올리는 작업이 곧 배포가 되고, 기본 HTTPS와 전 세계 전송망을 별도 설정 없이 사용할 수 있습니다.
전체 흐름을 짧게 정리하면 다음과 같습니다.
1. 정적 홈페이지를 만들고 로컬에서 확인합니다.
2. GitHub 저장소의 main 브랜치에 코드를 올립니다.
3. Cloudflare Pages에서 저장소를 연결합니다.
4. 빌드 명령과 출력 폴더를 프로젝트에 맞게 설정합니다.
5. pages.dev 주소에서 결과를 검증합니다.
6. 필요하면 사용자 도메인을 연결합니다.
7. 이후에는 Git push로 자동 배포합니다.
처음 배포할 때는 설정 항목이 많아 보이지만, 정적 사이트라면 한 번 연결한 뒤부터는 관리할 일이 크게 줄어듭니다. 비용 부담 없이 개인 홈페이지를 시작하고 싶다면 충분히 시도해 볼 만한 방법입니다.
참고 자료
• Cloudflare Pages Git 연동 안내: https://developers.cloudflare.com/pages/get-started/git-integration/
• Cloudflare Pages 무료 플랜 한도: https://developers.cloudflare.com/pages/platform/limits/