Cloudflare Pages 정적 블로그 배포 완벽 가이드: 주요 프레임워크 5가지 설정 실수 방지

블로그의 첫 글을 다 쓰고 ‘배포’ 버튼을 눌렀습니다. 3분 뒤 Cloudflare Pages에 ‘배포 성공’이 표시되어 링크를 브라우저에 붙여 넣었지만 페이지는 텅 비어 있었고, F12로 콘솔을 열자 온통 404 오류뿐이었습니다.

Astro 블로그를 처음 배포할 때의 막막함은 이렇습니다. Google에서 검색하면 답이 제각각이고, 서너 시간 동안 시도한 끝에 출력 디렉터리를 public으로 적었다는 사실을 발견합니다. Astro의 기본 출력 디렉터리는 dist입니다.

배포 실패의 90%는 빌드 명령과 출력 디렉터리라는 두 가지 설정을 정확히 이해하지 못해서 발생합니다. 이 글에서는 Astro, Hugo, Hexo, Gatsby, Eleventy라는 주요 프레임워크 5가지를 Cloudflare Pages에 배포할 때의 정확한 설정과 ‘빈 페이지’, ‘빌드 실패’ 문제를 빠르게 해결하는 방법을 설명합니다. 그대로 따라 하면 Git 저장소에서 사이트 공개까지 10분이면 됩니다.

Cloudflare Pages를 선택하는 이유와 2025년 플랫폼 변화

먼저 정적 블로그 배포에 Cloudflare Pages를 추천하는 이유부터 살펴보겠습니다.

무료이며 실제로 빠릅니다. Cloudflare는 전 세계에 300개가 넘는 데이터 센터를 운영합니다. 블로그는 이 노드들에 자동으로 배포되므로 독자가 어디서 접속하든 빠르게 열립니다. 이전에 GitHub Pages와 Vercel도 사용해 봤지만 Cloudflare Pages의 속도가 확실히 더 안정적이었고, 특히 중국 내 접속에서 그랬습니다. 게다가 완전히 무료이고 트래픽 제한이나 빌드 횟수 제한도 없습니다.

Git 자동 배포가 매우 편리합니다. GitHub 또는 GitLab 저장소를 한 번 연결하면 이후 git push할 때마다 Cloudflare가 자동으로 빌드하고 배포합니다. 각 Pull Request의 미리 보기 링크도 생성하므로 병합 전에 결과를 확인할 수 있습니다. 팀 협업에 특히 유용합니다.

무료 SSL 인증서와 사용자 지정 도메인이 기본 제공됩니다. 인증서 설정으로 씨름할 필요가 없고, 자체 도메인 연결도 간단하며 DNS 레코드는 몇 분 안에 적용됩니다.

다만 미리 알아둘 점이 있습니다. Cloudflare는 2025년 4월 플랫폼 전략을 조정해 Cloudflare Workers를 공식적으로 주력하기 시작했고, Pages 플랫폼은 사실상 ‘유지보수 모드’에 들어가 큰 기능 업데이트가 없을 예정입니다.

그렇다고 정적 블로그 배포에 큰 영향이 있는 것은 아닙니다. Pages는 여전히 안정적으로 사용할 수 있고 기능도 충분합니다. 복잡한 서버 측 렌더링이나 엣지 컴퓨팅 없이 블로그나 문서 사이트만 만들려면 Pages는 여전히 가장 좋은 선택입니다. Workers는 동적 기능, API 라우팅 또는 고급 엣지 컴퓨팅이 필요한 프로젝트에 더 적합합니다.

결론적으로 지금 순수 정적 블로그를 배포하려면 Pages를 안심하고 사용해도 됩니다. 나중에 서버 기능이 필요해지면 그때 Workers로 이전해도 늦지 않습니다.

주요 프레임워크 5가지의 표준 설정

이제 핵심 내용을 살펴보겠습니다. 다음은 제가 정리한 주요 정적 블로그 프레임워크 5가지의 정확한 설정입니다. 표에 나온 대로 입력하면 됩니다.

빠른 설정표

이 표는 꼭 저장해 두세요. 각 설정을 직접 검증했습니다. 이제 프레임워크별로 주의할 점을 자세히 살펴보겠습니다.

Astro 설정

Astro는 제가 현재 가장 즐겨 쓰는 정적 블로그 프레임워크입니다. 성능이 좋고 작성 경험도 편합니다.

표준 설정:

• 빌드 명령: npm run build 또는 astro build
• 출력 디렉터리: dist

순수 정적 사이트(SSG)라면 기본 설정을 그대로 사용하면 됩니다. 하지만 서버 측 렌더링(SSR)을 사용하려면 먼저 @astrojs/cloudflare 어댑터를 설치하고 astro.config.mjs에 다음 내용을 추가해야 합니다.

import cloudflare from '@astrojs/cloudflare';
export default {
  output: 'server',
  adapter: cloudflare()
};

출력 디렉터리를 build처럼 사용자 지정하려면 설정 파일에서 다음과 같이 지정할 수 있습니다.

export default {
  outDir: 'build'
};

하지만 기본값인 dist를 그대로 쓰는 것을 권합니다. 나중에 협업할 때 다른 사람이 설정을 이해하기도 더 쉽습니다.

Hugo 설정: 오류가 가장 잦은 프레임워크

Hugo는 함정이 가장 많습니다. 저도 처음 Hugo 블로그를 배포했을 때 밤새 씨름한 끝에야 원인을 이해했습니다.

표준 설정:

• 빌드 명령: hugo 또는 hugo -b $CF_PAGES_URL
• 출력 디렉터리: public
• 환경 변수(필수): HUGO_VERSION = 0.143.1 또는 필요한 버전

중요한 점은 Cloudflare Pages가 기본으로 사용하는 Hugo 버전은 2019년에 나온 오래된 0.54라는 사실입니다. 현재 대부분의 Hugo 테마는 0.80 이상, 심지어 0.120 이상을 요구합니다. HUGO_VERSION을 직접 설정하지 않으면 배포가 실패합니다.

환경 변수 설정 방법은 뒤의 ‘실전 과정’에서 자세히 설명하겠습니다. 여기서는 Cloudflare Pages 프로젝트 설정의 Settings > Environment variables로 이동해 다음 변수를 추가해야 한다는 점만 기억하세요.

• 변수 이름: HUGO_VERSION
• 값: 0.143.1(반드시 0.143.1처럼 정확한 버전 번호를 쓰고 0.143으로 줄이면 안 됨)

Hugo의 baseURL 설정에도 작은 주의점이 있습니다. 자체 도메인이 아니라 Cloudflare가 제공하는 .pages.dev 도메인을 사용한다면 빌드 명령을 다음처럼 입력해야 합니다.

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

hugo -b $CF_PAGES_URL

$CF_PAGES_URL은 Cloudflare가 자동으로 제공하는 환경 변수입니다. 배포 환경에 따라 올바른 도메인을 자동으로 설정하므로 내부 링크, RSS, sitemap 등이 정상적으로 작동합니다.

Hexo 설정

Hexo는 오래된 정적 블로그 프레임워크로 설정이 비교적 간단합니다.

표준 설정:

• 빌드 명령: hexo generate(줄여서 hexo g도 가능)
• 출력 디렉터리: public

Hexo는 대체로 큰 문제가 없지만 일부 테마나 플러그인이 특정 Node.js 버전을 요구합니다. 빌드가 실패하면 NODE_VERSION 환경 변수를 설정해 보세요.

• 변수 이름: NODE_VERSION
• 값: 14.3 또는 18.17.0(프로젝트에서 사용하는 버전에 맞춤)

로컬에서 node -v를 실행해 현재 버전을 확인한 뒤 Cloudflare Pages에도 같은 버전을 설정할 수 있습니다.

Gatsby 설정

Gatsby는 가장 간단하며 오류가 거의 없습니다.

표준 설정:

• 빌드 명령: gatsby build
• 출력 디렉터리: public

이게 전부입니다. 추가 설정 없이 그대로 입력하면 됩니다. 지인의 Gatsby 블로그를 여러 개 배포해 봤지만 문제가 발생한 적이 없습니다.

Eleventy 설정

Eleventy(11ty)는 가벼운 정적 사이트 생성기로 설정도 간단합니다.

표준 설정:

• 빌드 명령: npx @11ty/eleventy
• 출력 디렉터리: _site(밑줄로 시작한다는 점에 주의)

출력 디렉터리는 _site이며 앞에 밑줄이 있습니다. 실수로 site라고 쓰면 파일을 찾지 못합니다.

출력 디렉터리를 사용자 지정하려면 프로젝트 루트에 .eleventy.js 파일을 만들고 다음 내용을 추가할 수 있습니다.

module.exports = function(eleventyConfig) {
  return {
    dir: {
      output: "public"
    }
  };
};

Next.js 설정: 2025년의 새로운 변화

Next.js로 블로그를 만든다면 2025년에 생긴 중요한 변화를 알아야 합니다.

표준 설정(2025년 새 방식):

• 빌드 명령: npx opennextjs-cloudflare
• 출력 디렉터리: .worker-next

중요: 이전 튜토리얼에서 자주 쓰던 @cloudflare/next-on-pages 패키지는 더 이상 사용되지 않으니 피하세요. Cloudflare는 현재 새로운 @opennextjs/cloudflare 어댑터를 권장합니다.

오래된 튜토리얼에서 next-on-pages를 설명한다면 건너뛰세요. 이미 낡은 방식입니다. 새 방식의 설정 단계는 다음과 같습니다.

1. 의존성 설치: npm install @opennextjs/cloudflare
2. 빌드 명령 입력: npx opennextjs-cloudflare
3. 출력 디렉터리 입력: .worker-next

솔직히 말해 정적 블로그만 만들 생각이라면 Next.js를 그다지 권하지 않습니다. 동적 기능이 필요한 애플리케이션에 더 적합하며, 순수 정적 콘텐츠에는 Astro나 Hugo가 더 가볍고 빠릅니다.

실전: Git 저장소에서 사이트 공개까지 전체 과정

설정을 모두 알았으니 이제 처음부터 배포하는 과정을 하나씩 진행해 보겠습니다. 전체 과정은 약 10분이면 끝낼 수 있습니다.

사전 준비

시작하기 전에 다음 세 가지를 확인하세요.

1. 코드가 GitHub 또는 GitLab에 푸시되어 있음 - 저장소 페이지를 열고 최신 코드가 모두 올라가 있는지 확인합니다.
2. 프로젝트에 package.json이 있음(Node.js 프로젝트인 경우) - 모든 의존성이 파일에 기록되어 있는지 확인하고 로컬에만 설치한 의존성을 빠뜨리지 마세요.
3. .gitignore 확인 - node_modules, dist, public 등의 디렉터리가 .gitignore에 포함되어 있는지 확인하고 빌드 결과물을 푸시하지 마세요.

예전에 지인이 node_modules까지 Git에 푸시해 배포할 때 온갖 충돌이 발생한 적이 있습니다. 문제가 생기기 전에 .gitignore를 확인하세요.

자세한 배포 단계

1단계: Cloudflare에 로그인하고 Pages로 이동

dash.cloudflare.com을 열어 계정에 로그인합니다. 계정이 없다면 먼저 무료로 가입하세요.

왼쪽 메뉴에서 Workers & Pages를 찾아 들어간 뒤 오른쪽 위의 Create application 버튼을 클릭합니다.

2단계: ‘Git에 연결’ 선택

두 가지 옵션이 표시됩니다.

• Connect to Git - GitHub/GitLab에서 자동 배포(이 옵션 선택)
• Direct Upload - 파일 직접 업로드(매번 수동으로 올려야 하므로 권장하지 않음)

Connect to Git을 선택한 뒤 GitHub 또는 GitLab을 선택합니다.

3단계: 접근 권한 승인

처음 연결할 때는 Cloudflare가 Git 저장소에 접근하도록 승인해야 합니다. Sign in 버튼을 누르면 GitHub/GitLab 승인 페이지로 이동합니다.

권한 관련 팁: Cloudflare에 모든 저장소 접근 권한을 주고 싶지 않다면 ‘Only select repositories’를 선택해 특정 저장소만 승인할 수 있습니다.

승인이 끝나면 Cloudflare 페이지로 돌아옵니다.

4단계: 배포할 저장소 선택

저장소 목록에서 블로그 프로젝트를 찾아 클릭합니다.

저장소가 보이지 않으면 오른쪽 위의 새로 고침 버튼을 누르거나 이전 단계로 돌아가 다시 승인하세요.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

5단계: 빌드 설정 구성(핵심!)

가장 중요한 설정 단계입니다. 잘못 입력하지 않도록 주의하세요.

• Project name: 프로젝트 이름이며 .pages.dev 도메인의 일부가 됩니다. 예를 들어 my-blog를 입력하면 도메인은 my-blog.pages.dev가 됩니다.
• Production branch: 프로덕션 브랜치이며 일반적으로 main 또는 master를 입력합니다.
• Framework preset: 프레임워크 프리셋으로, 사용하는 프레임워크(Astro, Hugo 등)를 선택하거나 None을 선택할 수 있습니다.

핵심: Build settings

사용 중인 프레임워크에 맞는 정확한 설정을 앞의 설정표대로 입력합니다.

• Build command: 빌드 명령
  • Astro: npm run build
  • Hugo: hugo 또는 hugo -b $CF_PAGES_URL
  • Hexo: hexo generate
  • Gatsby: gatsby build
  • Eleventy: npx @11ty/eleventy
  • Next.js: npx opennextjs-cloudflare
• Build output directory: 출력 디렉터리
  • Astro: dist
  • Hugo: public
  • Hexo: public
  • Gatsby: public
  • Eleventy: _site
  • Next.js: .worker-next

Framework preset을 선택하면 Cloudflare가 일부 기본값을 자동으로 채우지만 정확하지 않을 수 있으므로 직접 다시 확인하는 것이 좋습니다.

6단계: 환경 변수 설정(필요한 경우)

아래로 스크롤해 **Environment variables (advanced)**를 찾고 Add variable을 클릭합니다.

프레임워크에 필요한 환경 변수를 추가합니다.

• Hugo 프로젝트 필수 항목:
  • Variable name: HUGO_VERSION
  • Value: 0.143.1(또는 필요한 버전, 반드시 세 자리까지 정확하게 입력)
• Hexo 프로젝트(필요한 경우):
  • Variable name: NODE_VERSION
  • Value: 14.3 또는 18.17.0(로컬 버전에 맞춤)

환경 변수 입력이 끝나면 설정이 완료됩니다.

7단계: 저장 및 배포

설정을 다시 확인한 뒤 페이지 아래의 Save and Deploy 버튼을 클릭합니다.

Cloudflare가 프로젝트 빌드를 시작하면 실시간 진행 상황이 표시되는 빌드 로그 페이지가 나타납니다. 일반적으로 1~3분이면 빌드가 완료됩니다.

8단계: 배포 결과 확인

빌드가 성공하면 페이지에 ‘Success! Your site is live!’라는 문구가 표시되고, 아래에 프로젝트이름.pages.dev 형식의 링크가 나타납니다.

링크를 클릭해 문제가 없다면 블로그가 표시됩니다.

환경 변수 설정 상세 설명

배포할 때 환경 변수를 바로 설정할 수 있지만, 당시 설정하지 않았거나 수정해야 한다면 다음과 같이 진행하세요.

1. Cloudflare Pages 프로젝트로 이동합니다.
2. 위쪽의 Settings 탭을 클릭합니다.
3. 왼쪽 메뉴에서 Environment variables를 선택합니다.
4. Add variable 버튼을 클릭합니다.
5. 변수 이름과 값을 입력하고 Save를 클릭합니다.

자주 쓰는 환경 변수:

• HUGO_VERSION: Hugo 버전 번호(예: 0.143.1)
• NODE_VERSION: Node.js 버전 번호(예: 18.17.0)
• CF_PAGES_URL: Cloudflare가 자동으로 제공하므로 직접 설정할 필요가 없으며 baseURL에 사용

중요: 환경 변수를 수정한 뒤에는 다시 배포해야 적용됩니다. Deployments 탭으로 이동해 최신 배포를 찾고 오른쪽의 점 세 개를 클릭한 뒤 Retry deployment를 선택합니다.

미리 보기 배포(Preview Deployments)

매우 유용한 기능이 하나 더 있습니다. Pull Request를 만들 때마다 Cloudflare가 미리 보기 링크를 자동으로 생성합니다.

예를 들어 GitHub에서 새 글을 병합하기 위한 PR을 만들면 Cloudflare는 이 PR의 코드를 자동으로 빌드하고 독립된 미리 보기 주소를 생성합니다. 먼저 결과를 확인하고 문제가 없을 때 메인 브랜치에 병합할 수 있습니다.

팀 협업에 특히 유용하며 여러 사람이 블로그를 쓸 때 서로 콘텐츠를 검토할 수 있습니다.

문제가 생겼을 때: 일반적인 오류와 해결 방법

배포 과정에서 문제가 생겨도 당황하지 마세요. 가장 흔한 오류 세 가지와 점검 방법을 정리했습니다. 대부분의 경우를 해결할 수 있습니다.

문제 1: 빌드 실패(Building Failed)

증상: 배포가 ‘Building’ 상태에서 멈춘 뒤 ‘Build failed’가 표시되고 페이지에 빨간색 오류 아이콘이 나타납니다.

제가 가장 많이 겪은 문제입니다. 바로 다시 배포하지 말고 먼저 오류 로그를 확인하세요.

점검 순서:

1. 빌드 로그 확인
   • 배포 실패 페이지에서 View build log 또는 Deployment details를 클릭합니다.
   • 맨 아래로 스크롤해 빨간색 오류 메시지를 찾습니다.
   • 마지막 몇 줄에 오류 원인이 나오는 경우가 많으므로 집중해서 확인합니다.
2. 빌드 명령이 올바른지 확인
   • Settings > Build & deployments로 돌아갑니다.
   • Build command가 앞의 설정표와 같은지 확인합니다.
   • 일반적인 실수: npm run build를 npm build로 입력해 run을 빠뜨림
3. 의존성이 완전한지 확인
   • 오류 로그에 ‘Cannot find module’ 또는 ‘Command not found’가 있다면 의존성이 누락된 것입니다.
   • package.json에 해당 패키지가 있는지 확인하세요.
   • 로컬에는 설치했지만 package.json에 추가하지 않았을 수 있습니다. npm install --save로 설치하면 자동으로 추가됩니다.
4. 프레임워크 버전 확인
   • Hugo 프로젝트: 빌드 실패의 99%는 HUGO_VERSION을 설정하지 않아 발생합니다.
     • 오류 로그에 ‘Theme requires Hugo Extended version’이 표시될 수 있습니다.
     • Settings > Environment variables에서 HUGO_VERSION = 0.143.1을 추가합니다.
   • Hexo 프로젝트: Node.js 버전이 맞지 않을 수 있습니다.
     • NODE_VERSION = 18.17.0 또는 로컬에서 쓰는 버전을 설정합니다.

실제 사례: 지인의 Hugo 블로그를 배포할 때 빌드 로그에 ‘Hugo version 0.54.0 does not support this theme’이 표시됐습니다. 확인해 보니 역시 버전이 너무 오래됐습니다. HUGO_VERSION = 0.120.0 환경 변수를 추가하고 다시 배포하자 바로 통과했습니다.

문제 2: 빈 페이지(가장 흔함)

증상: 배포는 성공했지만 사이트에 접속하면 빈 페이지만 보입니다. F12로 콘솔을 열면 404 오류가 많이 표시될 수 있습니다.

이 문제는 여러 번 겪었는데, 90%는 출력 디렉터리를 잘못 입력한 경우였습니다.

점검 순서:

1. 브라우저 개발자 도구 열기(F12)
   • Console 탭에서 오류가 있는지 확인합니다.
   • Network 탭에서 페이지를 새로 고침하고 어떤 리소스가 404인지 확인합니다.
   • Sources 탭에서 파일 구조가 올바른지 확인합니다.
2. 출력 디렉터리 설정 확인
   • 가장 흔한 원인으로 90%를 차지합니다.
   • Cloudflare Pages의 Settings > Build & deployments로 돌아갑니다.
   • Build output directory가 올바른지 확인합니다.
   • 일반적인 실수:
     • Astro 프로젝트에 dist 대신 public 입력
     • Hugo 프로젝트에 public 대신 dist 입력
     • Eleventy 프로젝트에 _site 대신 site 입력(밑줄 누락)
3. baseURL 또는 publicPath 설정 확인
   • example.com/blog 같은 하위 경로에 배포한다면 baseURL을 설정해야 할 수 있습니다.
   • Hugo 프로젝트: 빌드 명령을 hugo -b $CF_PAGES_URL로 변경합니다.
   • Astro 프로젝트: astro.config.mjs에 base: '/blog'를 설정합니다.
   • Vue/React 프로젝트: 상대 경로인 publicPath: './'을 설정해야 할 수 있습니다.
4. 라우팅 모드 확인(SPA 애플리케이션)
   • Vue Router 또는 React Router의 history 모드를 사용하면 서버가 해당 파일을 찾지 못해 페이지를 새로 고칠 때 404가 발생할 수 있습니다.
   • 해결 방법:
     • URL에 #이 들어가는 hash 모드로 변경합니다.
     • 또는 프로젝트 루트에 _redirects 파일을 만들고 다음 내용을 씁니다.

       /* /index.html 200

실제 사례: 지난번 제 Astro 블로그를 배포했을 때 페이지가 텅 비어 있었습니다. 한참 확인한 끝에 출력 디렉터리를 public으로 입력했다는 사실을 발견했고, dist로 바꾸자 해결됐습니다. 때로는 정말 이처럼 단순한 실수입니다.

문제 3: 스타일 또는 리소스 로딩 실패

증상: 페이지는 표시되지만 스타일이 모두 깨지고 이미지가 로드되지 않아 CSS가 전혀 없는 것처럼 보입니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

점검 순서:

1. 개발자 도구에서 Network 탭 확인
   • CSS, JS, 이미지 파일이 404인지 확인합니다.
   • 리소스 요청 경로가 올바른지 확인합니다.
2. 리소스 참조 경로 확인
   • 상대 경로와 절대 경로 문제
   • HTML에 /assets/style.css 같은 절대 경로가 있는데 하위 경로에 배포했다면 파일을 찾지 못합니다.
   • 해결 방법: 프레임워크가 제공하는 리소스 처리 방식을 사용합니다.
     • Astro: import로 리소스 가져오기
     • Hugo: .RelPermalink 또는 absURL 사용
     • Hexo: url_for() 헬퍼 함수 사용
3. CDN 설정 확인
   • jsDelivr, cdnjs 같은 외부 CDN을 사용한다면 해당 CDN 링크가 차단되지 않았는지 확인합니다.
   • BootCDN 같은 중국 내 CDN으로 바꿀 수 있습니다.

실제 사례: 이전에 지인의 Hexo 블로그를 배포했을 때 페이지는 표시됐지만 스타일이 없었습니다. 소스를 확인해 보니 CSS 경로는 /css/style.css였지만 실제 파일은 /blog/css/style.css에 있었습니다. 블로그를 하위 경로에 배포하면서 Hexo 설정 파일의 url과 root를 바꾸지 않은 것이 원인이었습니다. _config.yml에 root: /blog/를 추가하고 다시 생성하자 해결됐습니다.

빠른 점검 목록

문제가 생기면 다음 순서대로 확인하세요. 대부분 해결할 수 있습니다.

1. ✓ 빌드 로그에서 오류 메시지 확인
2. ✓ 빌드 명령이 올바른지 설정표와 대조
3. ✓ 출력 디렉터리가 올바른지 설정표와 대조
4. ✓ 환경 변수가 설정되어 있는지 확인(Hugo 프로젝트는 HUGO_VERSION 필수)
5. ✓ 브라우저에서 F12를 열어 콘솔과 네트워크 요청 확인
6. ✓ .gitignore를 확인해 빌드 결과물이 Git에 푸시되지 않았는지 점검
7. ✓ 로컬에서 npm run build, hugo 등의 명령을 실행해 정상적으로 빌드되는지 확인

모두 확인했는데도 해결되지 않으면 Cloudflare 커뮤니티 포럼에서 도움을 요청하거나 공식 문서의 Troubleshooting 섹션을 살펴보세요.

고급 팁: 블로그를 더 전문적으로 만들기

블로그 공개는 시작일 뿐입니다. 어렵지 않으면서 경험을 크게 개선할 수 있는 몇 가지 팁을 소개합니다.

사용자 지정 도메인 연결

.pages.dev 도메인도 사용할 수 있지만 자체 도메인이 더 전문적으로 보입니다. 설정도 매우 간단하고 Cloudflare가 SSL 인증서도 무료로 제공합니다.

설정 단계:

1. GoDaddy, Alibaba Cloud, Tencent Cloud 같은 도메인 등록 업체에서 도메인을 구매합니다.
2. Cloudflare Pages 프로젝트로 이동해 Custom domains 탭을 클릭합니다.
3. Set up a custom domain을 클릭하고 blog.example.com 같은 도메인을 입력합니다.
4. Cloudflare가 제공하는 DNS 레코드를 도메인 등록 업체의 DNS 관리 페이지에 추가합니다.
5. DNS 레코드가 적용될 때까지 기다립니다. 보통 몇 분에서 몇 시간이 걸립니다.
6. 레코드가 적용되면 Cloudflare가 HTTPS 인증서를 자동으로 설정합니다.

팁: 도메인도 Cloudflare에서 관리한다면 DNS 적용이 더 빠르고 레코드를 직접 추가하지 않아도 자동으로 설정할 수 있습니다.

빌드 최적화: 빌드 속도 높이기

블로그 글이 많다면 빌드 시간이 길어질 수 있습니다. 다음 방법으로 최적화할 수 있습니다.

1. 캐시 활성화
   • Cloudflare Pages는 기본적으로 node_modules를 캐시합니다.
   • 빌드가 느리다면 매번 의존성을 다시 내려받고 있지 않은지 확인합니다.
2. 불필요한 의존성 줄이기
   • package.json을 확인하고 사용하지 않는 패키지를 삭제합니다.
   • jQuery처럼 CDN으로 불러올 수 있는 라이브러리는 프로젝트에 설치하지 않아도 됩니다.
3. 병렬 빌드
   • Hugo의 --gc 옵션은 캐시를 정리하며 경우에 따라 빌드 속도를 높입니다.
   • Astro에서는 experimental.contentCollectionCache 캐시를 활성화할 수 있습니다.
4. 브랜치 전략
   • 개발 중에는 dev 브랜치에서 작업하고 정식 공개할 때만 main에 병합할 수 있습니다.
   • 이렇게 하면 커밋할 때마다 프로덕션 빌드가 실행되지 않습니다.

성능 모니터링과 분석

블로그 방문 현황이 궁금하다면 Cloudflare가 제공하는 무료 분석 도구를 사용할 수 있습니다.

방문 데이터 확인:

1. Cloudflare Pages 프로젝트로 이동합니다.
2. Analytics 탭을 클릭합니다.
3. 다음 정보를 볼 수 있습니다.
   • 총 요청 수(Requests)
   • 대역폭 사용량(Bandwidth)
   • 방문자 국가(Requests by country)
   • 트래픽 추세 그래프

Web Vitals 성능 모니터링:

• Cloudflare는 페이지 로딩 속도, 상호작용 지연 같은 지표를 볼 수 있는 Web Vitals 모니터링도 제공합니다.
• 이 데이터는 사용자 경험 최적화에 특히 유용합니다.
• 특정 지표가 나쁘다면 이미지 압축이나 지연 로딩 같은 방법으로 해당 부분을 개선할 수 있습니다.

자동화 워크플로

한 단계 더 자동화하려면 GitHub Actions와 결합해 고급 기능을 구현할 수 있습니다.

예시 1: 글 예약 공개

• 글을 작성한 뒤 미래의 공개 시각을 설정합니다.
• GitHub Actions가 정기적으로 확인하고 시간이 되면 자동으로 공개합니다.

예시 2: sitemap 자동 생성

• 배포할 때마다 sitemap을 검색 엔진에 자동으로 제출합니다.

예시 3: 이미지 압축

• 푸시 전에 이미지를 자동으로 압축해 로딩 시간을 줄입니다.

필수 기능은 아니지만 블로그 운영을 훨씬 편하게 해 줍니다. 관심이 있다면 GitHub Actions를 살펴보세요. 커뮤니티에 사용할 수 있는 템플릿이 많이 있습니다.

결론

지금까지 많은 내용을 설명했지만 정적 블로그 배포는 사실 그렇게 복잡하지 않습니다. 핵심은 빌드 명령과 출력 디렉터리라는 두 가지 설정을 정확히 이해하는 것입니다. 앞의 설정표대로 올바르게 입력하면 문제의 90%를 피할 수 있습니다.

핵심 설정을 다시 정리했습니다. 이 표는 저장해 두는 것이 좋습니다.

문제가 생겨도 당황하지 마세요. 대부분 설정을 잘못 입력한 경우입니다. 먼저 빌드 로그를 확인하고 이 글의 점검 목록과 대조하면 대부분 해결할 수 있습니다.

지금 바로 시작해 보세요. Cloudflare Pages를 열고 Git 저장소를 연결한 뒤 올바른 설정을 입력하면 10분 후 블로그가 공개됩니다.

이 글이 도움이 되었다면 블로그 배포로 씨름하는 다른 사람에게도 공유해 주세요. 배포 과정에서 여기서 다루지 않은 문제가 생겼다면 댓글로 남겨 다른 사람에게도 도움이 되는 경험을 나눠 주세요.

배포도 글쓰기도 순조롭길 바랍니다!