Astro로 만든 콘텐츠 사이트가 요청마다 서버에서 HTML을 만들 필요는 없습니다. 모든 글이 저장소 안의 Markdown 파일이고 빌드할 때 내용이 확정된다면, 정적 사이트 생성(SSG) 이 가장 단순하고 빠른 선택입니다.

이 구성에서는 Astro가 빌드 시점에 모든 페이지를 HTML로 만들고, Cloudflare Workers는 완성된 파일을 전 세계 엣지에서 전달합니다. 방문자의 요청을 처리하는 Worker 코드가 없기 때문에 운영할 부분도 크게 줄어듭니다.

정적 출력을 명시하기

Astro는 어댑터가 없을 때 기본적으로 정적 출력을 사용합니다. 그래도 프로젝트의 의도를 분명하게 남기기 위해 설정에 output: "static"을 명시하는 편이 좋습니다.

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  site: "https://everything.jspark.dev",
  output: "static",
  trailingSlash: "always",
  build: {
    format: "directory",
  },
});

site는 canonical URL과 사이트맵처럼 절대 주소가 필요한 기능의 기준이 됩니다. trailingSlash와 build.format도 함께 맞춰 두면 개발 환경과 실제 파일 경로가 일관됩니다.

Cloudflare 어댑터가 필요 없는 이유

@astrojs/cloudflare 어댑터는 요청 시점 렌더링, 바인딩, 세션처럼 Worker 런타임이 필요한 경우에 사용합니다. 순수한 정적 사이트에 이 어댑터를 추가하면 필요하지 않은 서버 출력과 런타임 복잡성이 생깁니다.

정적 사이트에는 Wrangler가 dist 디렉터리만 업로드하도록 설정하면 충분합니다.

{
  "name": "everything-jspark-dev",
  "compatibility_date": "2026-08-19",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

main 필드가 없다는 점이 핵심입니다. 실행할 Worker 스크립트가 없고, 요청은 정적 자산 계층에서 끝납니다.

캐시는 파일 성격에 맞게

Astro가 생성한 /_astro/ 파일은 이름에 콘텐츠 해시가 포함됩니다. 내용이 바뀌면 URL도 바뀌므로 브라우저에 1년 동안 저장해도 안전합니다.

반면 HTML은 같은 URL의 내용이 바뀔 수 있습니다. Cloudflare의 기본 ETag 재검증을 활용하면 새 배포를 즉시 반영하면서도 변경되지 않은 파일의 재다운로드를 피할 수 있습니다.

오래 캐시해야 하는 것은 모든 파일이 아니라, URL에 버전이 포함된 불변 자산입니다.

배포 전 확인할 것

  1. bun run build가 타입 검사와 정적 빌드를 모두 통과하는지 확인합니다.
  2. dist에 각 글의 index.html, 404.html, 사이트맵과 RSS가 생성됐는지 봅니다.
  3. bun run preview로 Wrangler의 실제 정적 자산 라우팅을 확인합니다.
  4. 준비가 되면 bun run deploy로 빌드와 배포를 이어서 실행합니다.

정적 콘텐츠 사이트의 좋은 배포 구성은 눈에 띄지 않습니다. 빌드는 오류를 일찍 발견하고, 배포된 파일은 가까운 곳에서 빠르게 전달되며, 운영자는 런타임을 신경 쓰지 않아도 됩니다.