🚀 Cloudflare Pages로 사이트 올리기 — 가입부터 내 도메인 연결까지

만든 걸 인터넷에 올리려면 어딘가에 두어야 합니다. 예전엔 서버를 빌려야 했지만, HTML과 자바스크립트로만 된 사이트라면 지금은 무료로 됩니다. 저는 도구 네 개와 이 블로그를 전부 Cloudflare Pages에 올려두고 있어요. 왜 이 방식을 택했는지는 웹 도구 네 개를 서버 없이 운영합니다에 적었고, 여기서는 실제로 올리는 순서를 다룹니다.

미리 말해두면 대부분 화면에서 클릭하는 작업입니다. 명령어는 거의 없어요.

Pages에 올리는 방법은 두 가지입니다. 깃 저장소를 연결해 자동으로 배포하는 방식과, 만들어진 파일을 직접 올리는 방식이에요. 이 글은 앞쪽을 다룹니다. 코드를 저장소에 올리면 알아서 배포되니 손이 덜 갑니다.

여기서 미리 알아야 할 게 하나 있습니다. 공식 문서에 경고로 적혀 있는 내용이에요.

깃 연동으로 배포하기 시작하면 나중에 직접 업로드 방식으로 바꿀 수 없습니다.

프로젝트를 만들 때 정하는 것이고 되돌릴 수 없으니, 처음에 한 번 생각하고 고르시는 게 좋습니다. 대부분은 깃 연동이 편하지만, 빌드를 내 컴퓨터에서만 하고 싶다면 직접 업로드 쪽을 봐야 합니다 (출처: Cloudflare Pages 공식 문서 — Git integration guide).

준비물은 셋입니다. 깃허브(또는 깃랩) 계정, 올릴 코드가 담긴 저장소, 그리고 Cloudflare 계정. 마지막 것부터 만들면 됩니다.

1단계 — 계정 만들고 대시보드 들어가기

dash.cloudflare.com에서 가입합니다. 이메일과 비밀번호만 있으면 되고, 무료 플랜은 결제 수단을 등록하지 않아도 씁니다.

가입하면 도메인을 추가하라는 화면이 나올 수 있는데, 여기서는 건너뛰어도 됩니다. Pages는 도메인이 없어도 프로젝트이름.pages.dev 주소를 자동으로 주거든요. 내 도메인 연결은 마지막 단계에서 합니다.

로그인한 상태로 왼쪽 메뉴에서 Workers 및 Pages를 찾아 들어갑니다. 여기가 앞으로 계속 쓸 화면이에요.

2단계 — 저장소 연결하기

메뉴를 따라갑니다.

Workers 및 Pages → 애플리케이션 생성 → Pages → Git에 연결

깃허브 로그인 화면이 뜨고, Cloudflare가 저장소에 접근할 수 있게 허용해달라고 합니다. 여기서 한 가지 권합니다. 모든 저장소를 통째로 열어주지 말고 필요한 것만 고르세요. 나중에 저장소가 늘어나면 그때 추가하면 됩니다.

허용하고 나면 저장소 목록이 보입니다. 올릴 저장소를 고르고, 프로덕션 브랜치를 지정합니다. 대개 main이에요. 이 값이 실제 사이트로 나가는 브랜치이니 정확히 확인하세요.

3단계 — 빌드 설정 채우기

다음 화면에서 세 칸을 채웁니다.

항목	무엇을 넣나
프레임워크 프리셋	쓰는 것이 있으면 고르고, 순수 HTML이면 없음
빌드 명령	npm run build 같은 것. 빌드가 필요 없으면 비움
빌드 출력 디렉터리	결과물이 생기는 폴더. dist나 build가 흔함

프리셋을 고르면 나머지 둘이 자동으로 채워집니다. 다만 자동 감지가 틀릴 때가 있으니 값이 맞는지 눈으로 보세요.

여기서 가장 흔한 실패는 빌드 출력 디렉터리를 잘못 적는 것입니다. 내 컴퓨터에서 빌드해보고 어느 폴더에 결과가 생기는지 먼저 확인하는 편이 확실합니다.

npm run build
ls

만들어진 폴더 이름을 그대로 넣으면 됩니다. HTML 파일만 있는 사이트라면 빌드 명령은 비우고 출력 디렉터리에 /를 넣으면 되고요.

저장하면 첫 배포가 시작됩니다.

4단계 — 배포 결과 확인하기

몇 분 지나면 결과가 나옵니다. 여기를 그냥 넘기지 마세요.

프로젝트의 배포 탭에서 최신 커밋이 어떻게 끝났는지 봅니다. 성공하면 초록 체크와 함께 프로젝트이름.pages.dev 주소가 뜹니다. 눌러서 실제로 화면이 나오는지 봅니다. 실패했으면 빌드 로그를 열어 어디서 멈췄는지 확인하고요. 대개 빌드 명령이나 출력 디렉터리가 틀린 경우입니다.

“No deployment available”이 보이면 배포가 안 된 겁니다. 제가 여기서 시간을 꽤 썼어요. 코드를 고쳐 올렸는데 사이트가 그대로여서 코드를 계속 들여다봤는데, 알고 보니 배포 자체가 실패해 있었습니다. 로컬에서 되는 것과 사이트에서 되는 것은 별개입니다.

이후로는 저장소에 올리기만 하면 자동으로 배포됩니다.

git add .
git commit -m "메인 화면 문구 수정"
git push

5단계 — 내 도메인 연결하기

pages.dev 주소로도 쓸 수 있지만, 갖고 있는 도메인이 있다면 붙이는 게 낫습니다.

프로젝트를 열면 위쪽에 탭이 넷 있습니다. 배포 / 메트릭 / 사용자 설정 도메인 / 설정. 세 번째로 들어가 사용자 설정 도메인 설정 버튼을 누르고 도메인을 입력합니다.

그 도메인이 이미 Cloudflare에서 관리되고 있으면 나머지는 자동으로 됩니다. DNS 기록이 알아서 추가되고 인증서도 붙어요. 다른 곳에서 관리 중이라면 Cloudflare가 알려주는 값을 그쪽 관리 화면에 넣어야 합니다. 반영되는 데 시간이 걸릴 수 있으니 바로 안 열려도 조금 기다려보세요.

제대로 붙었으면 목록에 도메인이 뜨고 상태가 활성으로, 오른쪽에 SSL 사용됨으로 표시됩니다. 이 둘을 확인하고 넘어가면 됩니다.

무료 플랜도 프로젝트당 도메인을 100개까지 붙일 수 있습니다. 저는 도구마다 프로젝트를 따로 만들고 pdf. img. 처럼 서브도메인을 하나씩 붙여뒀어요. 이렇게 하면 한 도구를 고쳐도 다른 도구는 다시 빌드되지 않습니다.

처음에 걸리기 쉬운 것들

• 프로덕션 브랜치가 다른 경우 — 처음 올린 브랜치가 기본값이 됩니다. 다른 브랜치를 쓴다면 설정에서 바꿔야 하는데, 이걸 놓치면 고친 코드가 사이트에 안 나타납니다
• 빌드 횟수 — 무료 플랜은 월 500회입니다. 하루 16번꼴이라 보통은 넉넉한데, 고치고 올리기를 반복하는 날엔 생각보다 빨리 씁니다
• 한 파일이 25MiB를 넘는 경우 — 큰 영상이나 자료 파일은 올라가지 않습니다. 다른 저장소를 써야 해요
• 서버 쪽 코드를 쓰면 무료가 아닐 수 있음 — Pages에도 서버 코드를 돌리는 기능이 있는데, 이건 별도 사용량 계산에 들어갑니다. 정적 파일만 쓰면 해당 없습니다

정리

순서만 놓고 보면 다섯 단계입니다. 계정을 만들고, 저장소를 연결하고, 빌드 설정을 채우고, 배포 결과를 확인하고, 도메인을 붙이는 것.

이 중에서 가장 자주 놓치는 게 네 번째예요. 올렸으니 됐겠지 하고 넘어가면, 나중에 엉뚱한 곳에서 원인을 찾게 됩니다. 배포 목록에서 초록 체크를 한 번 보는 데 5초면 되니, 이것만은 습관으로 만들어두시길 권합니다.