이 글에서: Astro로 만든 정적 사이트를 Cloudflare에 배포합니다. 단, 2026년 기준으로는 Pages가 아니라 Workers가 권장 경로입니다. 그 이유부터 커스텀 도메인 연결까지, 그럼(grum.dev)을 Cloudflare Workers로 배포하며 검증한 절차를 태리가 정리했습니다. 급하면 “배포 단계”로 건너뛰세요.

왜 Pages가 아니라 Workers인가 (2026)

예전엔 “Astro + Cloudflare Pages”가 정석이었습니다. 그런데 2026년 현재 Cloudflare는 신규 프로젝트에 Cloudflare Workers를 권장합니다. Astro 공식 배포 문서도 “Cloudflare recommends using Cloudflare Workers for new projects” 라고 명시합니다. Pages가 사라지는 건 아니지만, 신규 기능 투자는 Workers 쪽으로 갑니다.

좋은 소식은, 순수 정적 사이트라면 거의 차이가 없다는 점입니다. output: 'static'(어댑터 없음) 상태면 @astrojs/cloudflare 어댑터도 필요 없습니다. Worker 코드 한 줄 없이, 빌드 결과물 dist/를 Static Assets로 서빙하면 끝입니다.

사전 준비

• Node.js 22+ (Astro 6 요구)
• Astro 정적 프로젝트 (이미 astro build가 dist/를 만드는 상태)
• Cloudflare 계정 (도메인 연결까지 하려면 도메인도 Cloudflare zone이면 가장 깔끔 — 뒤에서 설명)

배포 단계

1. wrangler 설치

npm install -D wrangler

wrangler는 Cloudflare 배포 CLI입니다. devDependency로 충분합니다.

2. wrangler.jsonc 작성

프로젝트 루트에 아래 파일을 만듭니다. 정적 사이트는 assets 한 블록이면 됩니다.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "grum-blog",
  "compatibility_date": "2026-06-20",
  // 순수 정적 사이트: Worker 스크립트 없이 dist/ 정적 자산만 서빙
  "assets": {
    "directory": "./dist"
  }
}

name은 Worker 이름입니다(나중에 자동배포를 붙이면 대시보드의 Worker 이름과 일치해야 합니다). directory는 Astro 빌드 출력 경로 ./dist.

3. 배포 스크립트와 .gitignore

package.json에 배포 스크립트를 추가합니다.

{
  "scripts": {
    "deploy": "astro build && wrangler deploy"
  }
}

그리고 .gitignore에 wrangler 로컬 상태를 추가합니다.

.wrangler/

4. 로그인

npx wrangler login

브라우저가 열리며 Cloudflare 인증을 진행합니다.

5. 배포

npm run deploy

astro build로 dist/를 만들고 wrangler deploy가 자산을 업로드합니다. 성공하면 https://<name>.<subdomain>.workers.dev 임시 URL이 출력됩니다. 접속해서 사이트가 뜨면 1차 성공입니다.

커스텀 도메인 연결

*.workers.dev 대신 내 도메인을 붙입니다. 도메인이 Cloudflare 계정의 zone이어야 합니다(예: Cloudflare Registrar에서 산 경우 자동 충족).

가장 깔끔한 방법은 wrangler.jsonc에 custom_domain 라우트를 선언하는 것입니다. 그러면 배포 시 Cloudflare가 DNS·인증서를 자동 프로비저닝합니다(코드로 관리 = IaC).

{
  // ...assets 블록 아래에 추가
  "routes": [{ "pattern": "grum.dev", "custom_domain": true }]
}

이후 npm run deploy 한 번이면 https://grum.dev가 인증서까지 자동으로 붙습니다. (대시보드에서 하려면 Workers & Pages → 해당 Worker → Settings → Domains & Routes → Add → Custom Domain, 또는 2026년에 새로 생긴 Domains 탭에서도 됩니다.)

www → apex 리다이렉트

커스텀 도메인은 정확한 호스트명 일치라, grum.dev와 www.grum.dev는 별개로 취급됩니다. www를 대표 주소로 보내려면 Cloudflare 대시보드에서:

1. 해당 zone → Rules → Redirect Rules → Create
2. 매칭: Wildcard 패턴 https://www.grum.dev/* — 프로토콜을 https로 고정하고 * 하나로 경로만 캡처합니다. 이렇게 해야 그 *가 ${1}(= 경로)이 됩니다.
3. 대상(동적): https://grum.dev/${1}, 상태 코드 301, Preserve query string(쿼리 문자열 보존) 켜기

⚠️ 와일드카드 캡처 주의: 패턴에 *를 여러 개 쓰면(예: http*://www.grum.dev/*) 캡처 순서가 밀립니다 — 첫 *가 프로토콜의 s를 잡아 ${1}이 경로가 아니게 됩니다. 그래서 프로토콜은 고정하고 경로 * 하나만 둡니다. (http로 들어오는 요청은 zone의 Always Use HTTPS가 먼저 https로 올린 뒤 이 룰이 처리합니다.) 쿼리 문자열은 와일드카드 캡처와 무관하게 Preserve query string 옵션으로 보존됩니다.

⚠️ 검증 중 확인된 함정: 리다이렉트 룰만 만들고 www의 DNS 레코드를 안 만들면 요청이 Cloudflare에 닿지조차 못합니다(curl에서 Could not resolve host). www에 프록시된(주황 구름) CNAME 레코드(www → grum.dev)를 추가해야 룰이 발동합니다.

확인

curl -I https://grum.dev
# HTTP/2 200

curl -I https://www.grum.dev
# HTTP/1.1 301 Moved Permanently
# location: https://grum.dev/

# 경로·쿼리까지 보존되는지 확인
curl -I "https://www.grum.dev/foo?x=1"
# HTTP/1.1 301 Moved Permanently
# location: https://grum.dev/foo?x=1

apex가 200, www가 301로 넘어가고 경로·쿼리(/foo?x=1)까지 그대로 보존되면 완성입니다. (이 출력은 grum.dev에서 검증한 결과입니다.)

자주 묻는 질문

Q. 이미 Cloudflare Pages로 배포 중인데 Workers로 옮겨야 하나요? A. 당장은 아닙니다. Pages는 계속 동작합니다. 다만 신규 프로젝트라면 Cloudflare 권장대로 Workers로 시작하는 게 장기적으로 안전합니다.

Q. *.workers.dev 주소는 꺼도 되나요? A. 커스텀 도메인을 붙였다면 끄는 걸 권합니다. 같은 콘텐츠가 두 URL로 노출되면 SEO에 불리합니다. wrangler.jsonc에서 workers_dev를 명시하지 않으면 라우트 추가 시 기본 비활성화됩니다.

Q. 매번 npm run deploy를 직접 해야 하나요? A. Workers Builds(git 연동)를 붙이면 main에 푸시/머지할 때 자동 배포됩니다. 대시보드 Worker → Settings → Builds → Connect로 GitHub 저장소를 연결하고, Build command npm run build, Deploy command npx wrangler deploy로 설정하면 됩니다.

Q. SSR(서버 렌더링)도 되나요? A. 됩니다. 그 경우 @astrojs/cloudflare 어댑터를 추가하면 Worker가 요청 시 렌더링합니다. 이 글은 정적 사이트 기준이라 어댑터 없이 자산만 서빙했습니다.

---

여기까지가 grum.dev를 Cloudflare Workers에 올리며 검증한 절차입니다. 정적 Astro 사이트라면 Worker 코드 한 줄 없이, 설정 파일 하나로 Cloudflare의 글로벌 엣지에 올릴 수 있습니다.