이 사이트는 빌드 없는 정적 HTML 묶음이고, Cloudflare Pages에 올라가 있습니다. 배포 명령은 package.json에 한 줄뿐입니다. 

{
  "scripts": {
    "deploy": "npx wrangler pages deploy . --project-name=sd-cat-playground"
  }
}

이 한 줄이 어떻게 동작하는지, 그리고 정적 사이트를 실제로 서비스할 때 챙겨야 할 것들을 정리합니다.

왜 Cloudflare Pages였나

정적 사이트 호스팅 선택지는 여럿입니다. 이 프로젝트의 기준은 이랬습니다.

  • 무료 범위가 넉넉할 것 — 대역폭 제한이 사실상 없습니다.
  • CDN이 기본 — 전 세계 엣지에서 서빙되므로 별도 설정이 필요 없습니다.
  • HTTPS 자동 — 인증서 발급과 갱신을 신경 쓰지 않아도 됩니다.
  • 빌드 없이 올릴 수 있을 것 — 프레임워크를 쓰지 않으므로 폴더를 그대로 올리면 끝나야 합니다.
  • CLI 배포 — 대시보드를 거치지 않고 명령 한 줄로 끝나는 것.

배포하기

wrangler는 Cloudflare의 공식 CLI입니다. npx로 실행하면 전역 설치 없이 쓸 수 있습니다. 

# 처음 한 번 — 브라우저가 열리며 계정 인증
npx wrangler login

# 배포
npm run deploy

명령을 뜯어보면 이렇습니다.

  • pages deploy — Pages 프로젝트로 배포
  • . — 현재 디렉터리 전체를 올림 (빌드 산출물 폴더가 없으므로)
  • --project-name — Pages 프로젝트 이름. 없으면 새로 만들지 물어봅니다

배포가 끝나면 <해시>.<프로젝트명>.pages.dev 형태의 미리보기 URL이 출력됩니다. 배포마다 고유 URL이 생기므로 변경 사항을 프로덕션에 반영하기 전에 확인할 수 있습니다. 문제가 있으면 대시보드에서 이전 배포로 즉시 롤백할 수도 있습니다.

올리지 말아야 할 것 제외하기

.로 통째로 올리므로 불필요한 파일이 딸려가지 않도록 해야 합니다. .gitignore에 있는 항목은 기본적으로 제외되지만, 확실히 하려면 .assetsignore 파일로 명시할 수 있습니다. 

# .assetsignore
node_modules
tools
content
.git
*.md

이 사이트의 경우 content/(본문 조각)와 tools/(빌드 스크립트)는 소스일 뿐 서비스될 필요가 없어 제외 대상입니다.

커스텀 도메인 연결

pages.dev 주소로도 동작하지만, 검색엔진과 애드센스를 고려하면 자체 도메인이 낫습니다. 연결 절차는 다음과 같습니다.

  1. Cloudflare 대시보드에서 해당 Pages 프로젝트 → Custom domains
  2. 도메인 입력 후 안내되는 DNS 레코드를 등록
  3. 도메인을 Cloudflare 네임서버로 옮겨두면 레코드가 자동 생성됩니다
  4. 인증서 발급까지 보통 몇 분에서 수십 분 소요

www 유무를 하나로 통일하는 것이 중요합니다. 같은 콘텐츠가 두 주소로 접근되면 검색엔진이 중복으로 인식합니다. 한쪽을 정본으로 정하고 나머지는 리다이렉트하세요. Pages에서는 _redirects 파일로 처리할 수 있습니다. 

# _redirects
https://www.example.com/*  https://example.com/:splat  301

여기에 각 페이지의 <head>에 canonical 링크를 넣어두면 더 확실합니다. 

<link rel="canonical" href="https://example.com/guide/cat-age.html" />

정적 사이트에서 놓치기 쉬운 파일들

배포는 됐는데 검색에 안 잡히거나 광고가 안 붙는 경우, 대개 이 파일들이 원인입니다. 전부 사이트 루트에 있어야 하고, 정확한 Content-Type으로 서빙되어야 합니다.

robots.txt

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap.xml

크롤러가 가장 먼저 찾는 파일입니다. 사이트맵 위치를 여기에 명시하는 것이 가장 확실한 전달 방법입니다.

sitemap.xml

페이지 목록을 검색엔진에 알려줍니다. 페이지가 늘어날 때마다 손으로 관리하면 반드시 빠뜨리므로, 빌드 스크립트가 자동 생성하게 만드는 편이 낫습니다. 이 사이트도 글 목록을 읽어 사이트맵을 함께 생성합니다. 

<url>
  <loc>https://example.com/guide/cat-age.html</loc>
  <lastmod>2026-09-07</lastmod>
  <changefreq>monthly</changefreq>
  <priority>0.8</priority>
</url>

ads.txt

애드센스를 쓴다면 필요합니다. 루트에 텍스트 파일 한 줄이면 됩니다. 

google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0

확인 방법: 배포 후 https://도메인/ads.txt를 브라우저에서 직접 열어보세요. 200으로 내용이 보여야 합니다. 애드센스 대시보드에 "ads.txt를 찾을 수 없음"이 뜨는 경우는 대개 파일이 루트가 아닌 하위 경로에 있거나, 리다이렉트에 걸려 있거나, 아직 반영 전인 상태입니다.

캐시 다루기

CDN의 장점이자 함정입니다. 배포했는데 브라우저에서 옛날 파일이 보인다면 캐시 문제입니다.

  • Pages는 배포마다 자산 해시가 바뀌므로 대부분 자동으로 해결됩니다.
  • 그래도 남는다면 대시보드에서 캐시 퍼지, 또는 시크릿 창에서 확인하세요.
  • _headers 파일로 경로별 캐시 정책을 직접 지정할 수 있습니다. 
# _headers
/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*.html
  Cache-Control: public, max-age=0, must-revalidate

이미지·폰트처럼 잘 바뀌지 않는 것은 길게, HTML은 짧게 가져가는 것이 기본 전략입니다.

배포 전 체크리스트

  • 모든 페이지에 <title>과 meta description이 서로 다른 값으로 들어갔는가
  • canonical 링크가 정확한가
  • 내부 링크가 절대 경로(/guide/...)로 통일되어 있는가
  • 이미지에 width/height가 지정되어 레이아웃 밀림이 없는가
  • robots.txt, sitemap.xml, ads.txt가 루트에서 200으로 열리는가
  • 모바일 화면에서 가로 스크롤이 생기지 않는가
  • 404 페이지가 준비되어 있는가 (404.html을 루트에 두면 자동 사용)

배포 후에 할 일

  1. Google Search Console에 도메인을 등록하고 사이트맵을 제출합니다. 색인 여부와 검색 유입 키워드를 여기서 확인합니다.
  2. PageSpeed Insights로 모바일 점수를 확인합니다. 정적 사이트는 대체로 잘 나오지만, 이미지 크기와 폰트 로딩에서 점수가 깎이는 경우가 많습니다.
  3. 실제 모바일 기기에서 직접 열어봅니다. 개발자 도구의 반응형 모드만으로는 놓치는 것이 있습니다.

정리

빌드 과정이 없는 정적 사이트라면 npx wrangler pages deploy . 한 줄로 배포가 끝납니다. 실제로 손이 가는 부분은 배포 자체가 아니라 도메인 정본 통일, robots·sitemap·ads.txt의 루트 배치, 캐시 정책 쪽입니다. 이 셋만 제대로 잡아두면 이후로는 명령 한 줄로 운영할 수 있습니다.