wrangler.jsonc 설정

wrangler.jsonc는 Cloudflare Workers/Pages 프로젝트의 런타임 설정 파일입니다. 바인딩(D1, KV, R2 등), 호환성 플래그, 빌드 출력 경로를 선언합니다.

파일 형식

Wrangler는 .jsonc 확장자를 지원합니다. JSONC(JSON with Comments)는 주석을 허용하므로 설정 의도를 코드 옆에 기록할 수 있습니다.

{
  // 이 주석은 유효합니다
  "name": "my-project",
  /* 블록 주석도 가능합니다 */
  "compatibility_date": "2026-03-01"
}

참고: wrangler.json도 사용 가능하지만, 주석이 필요한 경우 .jsonc를 사용하세요. wrangler.toml은 레거시 형식이며, JSON 기반 설정이 권장됩니다.

필수 필드

모든 CF Pages 프로젝트에 반드시 포함해야 하는 필드입니다.

필드	설명	예시
`pages_build_output_dir`	정적 에셋 출력 경로	`"./dist"`
`compatibility_date`	Workers 런타임 호환성 기준 날짜	`"2026-03-01"`
`compatibility_flags`	런타임 기능 플래그 배열	`["nodejs_compat"]`

compatibility_date는 Cloudflare가 런타임 동작 변경을 관리하는 방식입니다. 이 날짜 이전에 도입된 모든 변경 사항이 적용됩니다. 새 프로젝트는 가능한 최근 날짜로 설정하세요.

nodejs_compat 플래그

nodejs_compat는 사실상 필수 플래그입니다. 많은 npm 패키지가 Buffer, crypto, stream 등 Node.js 내장 API에 의존하며, 이 플래그 없이는 런타임에서 실패합니다.

{
  "compatibility_flags": ["nodejs_compat"]
}

이 플래그가 활성화되면 Workers 런타임에서 다음 Node.js API를 사용할 수 있습니다.

node:buffer, node:crypto, node:util
node:stream, node:events
node:path, node:url, node:querystring
node:assert, node:string_decoder

주의: 모든 Node.js API가 지원되는 것은 아닙니다. node:fs, node:child_process 등 OS 의존 모듈은 Workers 환경에서 사용할 수 없습니다.

바인딩 설정

바인딩은 Workers/Pages 함수에서 Cloudflare 서비스에 접근하기 위한 선언입니다.

서비스	키	필수 필드
KV Namespace	`kv_namespaces`	`binding`, `id`
D1 Database	`d1_databases`	`binding`, `database_name`, `database_id`
R2 Bucket	`r2_buckets`	`binding`, `bucket_name`
Durable Objects	`durable_objects.bindings`	`name`, `class_name`
Hyperdrive	`hyperdrive`	`binding`, `id`

Hyperdrive는 Neon Postgres, Turso 등 외부 데이터베이스에 연결할 때 사용합니다. 각 바인딩의 구체적인 설정은 아래 전체 예시를 참고하세요.

Astro 프로젝트 특이사항

@astrojs/cloudflare 어댑터를 사용하면, 빌드 시 wrangler.json이 자동 생성됩니다. 이 경우 프로젝트 루트에 wrangler.jsonc를 직접 작성하면 어댑터가 생성한 파일과 충돌할 수 있습니다.

권장 방식은 astro.config.mjs에서 어댑터 옵션으로 바인딩을 선언하고, 별도의 wrangler.jsonc에는 어댑터가 다루지 않는 설정만 추가하는 것입니다.

전체 예시

실제 Modfolio 프로젝트에서 사용하는 설정 예시입니다.

{
  // CF Pages 프로젝트 설정
  "name": "naviaca",
  "pages_build_output_dir": ".svelte-kit/cloudflare",
  "compatibility_date": "2026-03-01",
  "compatibility_flags": ["nodejs_compat"],

  // D1 데이터베이스
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "naviaca-db",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],

  // KV 캐시
  "kv_namespaces": [
    {
      "binding": "SESSION_KV",
      "id": "abcdef1234567890abcdef1234567890"
    }
  ],

  // R2 파일 스토리지
  "r2_buckets": [
    {
      "binding": "FILES",
      "bucket_name": "naviaca-files"
    }
  ],

  // 외부 DB (Neon Postgres via Hyperdrive)
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  ]
}

다음 단계

환경변수 관리 – Doppler를 통한 시크릿 관리
커스텀 도메인 – DNS 설정과 도메인 연결