Wrangler 設定

Workers と Pages 用の wrangler.toml 設定

基本構造

wrangler.toml ファイルは Cloudflare プロジェクトを設定する。Pages プロジェクトでは主にバインディングと互換性設定を定義する：

# Cloudflare Pages project configuration
compatibility_date = "2024-12-01"

スタンドアロン Workers ではエントリーポイントとルーティングも含む：

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"

TOML のテーブルスコープ

wrangler.toml は素の TOML であり、TOML のテーブルのルールがそのまま適用される。[vars]、[assets]、[env.preview] のようなテーブルヘッダーを書いた時点で、それに続く裸の key = value 行はすべてそのテーブルに属する。トップレベルには属さない。次の [...] ヘッダーが現れるまでこれは続く。ファイルの末尾にフィールドを追記する際、自分が今どのテーブルの中にいるかを確認しないとこれで足をすくわれる：

[assets]
directory = "./dist"
binding = "ASSETS"

# Intended as a top-level setting, but it lands inside [assets] because
# no new table header appeared above it.
workers_dev = false

wrangler はこの位置ずれを無害なノイズとして黙って受け入れたりしない。各テーブルの既知のフィールドを検証し、属さないものを報告する：

Unexpected fields found in assets field: "workers_dev"

これは警告であってハードエラーではない。ビルド自体は通るが、意図した場所に適用されずフィールドが捨てられるだけだ。workers_dev は一切効かなくなり、長いデプロイログの中では見落としやすいミスになる。

バインディング

バインディングはコードを Cloudflare サービスに接続する。

KV ネームスペース

[[kv_namespaces]]
binding = "MY_KV"
id = "abc123def456ghi789"

D1 データベース

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "abc123-def456-ghi789"

R2 バケット

[[r2_buckets]]
binding = "FILES"
bucket_name = "my-files"

環境変数

[vars]
API_ENDPOINT = "https://api.example.com"

シークレット（API キー、トークン）には wrangler secret put を使用：

npx wrangler secret put MY_SECRET

必須シークレットの宣言

シークレット自体は wrangler.toml に書かないが、Worker が期待するシークレット名は [secrets] テーブルで宣言できる：

[secrets]
required = ["STRIPE_KEY", "SESSION_SECRET"]

これは値を設定するものではない。wrangler が dev 時とデプロイ時に強制するチェックリストだ：

• wrangler dev: 必須シークレットが欠けていても警告にとどまり、起動は止まらない -- Missing required secrets: STRIPE_KEY. Add them to .dev.vars, .env, or set as environment variables. Worker はそのまま起動し、そのシークレットは単に env に存在しないだけになる。

• 新規 Worker の初回デプロイ: 必須シークレットが欠けているとハードエラーでデプロイが止まる -- The following required secrets have not been set: STRIPE_KEY. Use wrangler secret put <NAME> to set secrets before deploying.

• 既存 Worker の再デプロイ: wrangler はまず前バージョンの値を継承するよう API に依頼し、即座には失敗させない。そのシークレットが本当に一度も設定されていなければ API が継承を拒否し、wrangler は同じ「required secrets have not been set」エラーを再度出す -- 失敗自体は変わらず、API のラウンドトリップが一往復増えるだけだ。

[secrets]
required = ["STRIPE_KEY", "SESSION_SECRET"]

[env.preview.secrets]
required = ["STRIPE_KEY", "SESSION_SECRET"]

wrangler deploy は [vars] を丸ごと置き換える

デフォルトでは、wrangler deploy のたびに**Worker 上に現在ある vars をすべて削除し、wrangler.toml が宣言するものだけに置き換える。**Cloudflare ダッシュボードから応急処置で var を追加していても、次の設定駆動のデプロイでそれは黙って消える -- マージは行われない。

npx wrangler deploy --keep-vars

--keep-vars を使うと削除してから再作成するステップをスキップし、ダッシュボードで設定した vars を wrangler.toml が宣言するものと並存させたまま残す。設定ファイルの外で vars が設定されている可能性がある場合は常にこれを使う。シークレットはどちらの場合でも影響を受けない -- wrangler deploy はこのフラグの有無にかかわらずシークレットを削除しないので、このトラップは [vars] に固有のものだ。

Pages 固有のオプション

pages_build_output_dir = "./dist"

[cache] テーブル

[cache]
enabled = true

[cache] は許可されたフィールドが enabled（boolean）ひとつだけの、正当で有効な wrangler.toml テーブルだ。それ以外のキーを入れると、前述の「Unexpected fields」チェックに同じように引っかかる。このページの他のテーブルより新しくドキュメント化も薄いため、一部エディタの汎用 TOML/JSON スキーマ linter は未知のキーとしてフラグを立てることがある。wrangler 自体は何の問題もなく受け付けているにもかかわらずだ。[cache] の下にエディタが引く赤い波線は、古くなったスキーマのせいだと考えて構わない。エディタの下線ではなく、ファイル全体を検証する wrangler deploy --dry-run で確認すること。

複数バインディングの例

# Cloudflare Pages project configuration
compatibility_date = "2024-12-01"
pages_build_output_dir = "./dist"

[vars]
AUTH0_DOMAIN = "placeholder.us.auth0.com"
AUTH0_CLIENT_ID = "placeholder"

[[d1_databases]]
binding = "DB"
database_name = "my-app"
database_id = "placeholder"

[[r2_buckets]]
binding = "FILES"
bucket_name = "my-app-files"

[[kv_namespaces]]
binding = "CACHE"
id = "placeholder"

名前付き環境とサービスバインディング

実際のプロジェクトでバインディングのセットがひとつだけということはまずない。通常は使い捨てデータを指す preview デプロイ、本番データを指す production デプロイ、そしてその中間の staging デプロイがほしくなる。Wrangler はこれを名前付き環境でモデル化する：[env.preview]、[env.production]、[env.staging]。特定の環境は --env でデプロイする：

npx wrangler deploy --env preview
npx wrangler deploy --env production

最大の落とし穴: バインディングと [vars] は継承されない

これはマルチ環境 Worker が壊れる最も一般的な原因だ。トップレベルで宣言したバインディング（D1、R2、KV、AI、サービス）と [vars] は、名前付き環境には引き継がれない。 --env preview でデプロイすると、Worker は [env.preview.*] の下に宣言されたものしか見えず、トップレベルの [vars] やバインディングは黙って捨てられる。

その結果、Worker は D1 接続もなく、KV もなく、API_ENDPOINT が未定義のまま preview で動き、リクエスト時になって初めて失敗することが多い。Wrangler はデプロイ時に警告を出す：

Processing wrangler.toml configuration:
  - "vars" exists at the top level, but not on "env.preview".
    This is not what you probably want, since "vars" is not inherited by environments.
    Please add "vars" to "env.preview".

修正方法は、各環境の中ですべてのバインディングと var を再宣言すること：

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"

# Top-level [vars] is NOT inherited by named environments below.
# Re-declare it under each [env.*] or the Worker runs without it.
[vars]
API_ENDPOINT = "https://api.example.com"

[env.preview]
# Wrangler does NOT copy the top-level [vars] here. Without this block the
# preview Worker runs with API_ENDPOINT undefined.
[env.preview.vars]
API_ENDPOINT = "https://api-preview.example.com"

[[env.preview.kv_namespaces]]
binding = "CACHE"
id = "placeholder-preview-kv-id"

[env.production]
[env.production.vars]
API_ENDPOINT = "https://api.example.com"

[[env.production.kv_namespaces]]
binding = "CACHE"
id = "placeholder-production-kv-id"

name = "my-site"
main = "./dist/_worker.js"
compatibility_date = "2024-12-01"

[assets]
directory = "./dist"
binding = "ASSETS"

# env.preview declares no [env.preview.assets] block at all,
# so it inherits the top-level [assets] above unchanged.
[env.preview]

環境ごとのデータ分離

各環境に独自の database_id と bucket_name を持たせることが、staging のトラフィックを本番データに触れさせないための鍵だ。バインディング名（DB、BUCKET）は同じままにするので Worker のコードは環境非依存になり、変わるのは背後のリソースだけになる：

name = "sync-server"
main = "src/index.ts"
compatibility_date = "2025-04-01"

[[d1_databases]]
binding = "DB"
database_name = "sync-db"
database_id = "placeholder-prod-d1-id"

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "sync-blobs"

[ai]
binding = "AI"

# Staging points the SAME bindings (DB, BUCKET, AI) at SEPARATE resources,
# so staging never reads or writes production data.
[env.staging]
name = "sync-server-staging"

[[env.staging.d1_databases]]
binding = "DB"
database_name = "sync-db-staging"
database_id = "placeholder-staging-d1-id"

[[env.staging.r2_buckets]]
binding = "BUCKET"
bucket_name = "sync-blobs-staging"

[env.staging.ai]
binding = "AI"

参照する前に staging リソースを作成するには：

npx wrangler d1 create sync-db-staging
npx wrangler r2 bucket create sync-blobs-staging

返ってきた database_id を [[env.staging.d1_databases]] に貼り付ける。

サービスバインディング: ある Worker が別の Worker を呼ぶ

サービスバインディングを使うと、ある Worker が別の Worker を Cloudflare の内部エッジ経由で直接呼び出せる。呼び出しが Cloudflare のネットワークを出ないため、公開インターネットの経由も、DNS ルックアップも、CORS もない。論理的な名前をデプロイ済み Worker の名前にバインドする：

[env.preview]

# Service binding: this preview Worker → the "image-resizer-preview" Worker.
# The caller reaches it via env.IMAGE_RESIZER without a public request.
[[env.preview.services]]
binding = "IMAGE_RESIZER"
service = "image-resizer-preview"

[[env.preview.services]]
binding = "NOTIFY_WORKER"
service = "notify-worker-preview"

[env.production]

# Same logical bindings, wired to the production target Workers.
[[env.production.services]]
binding = "IMAGE_RESIZER"
service = "image-resizer-prod"

[[env.production.services]]
binding = "NOTIFY_WORKER"
service = "notify-worker-prod"

バインディング名（IMAGE_RESIZER）は環境をまたいで一定なのに対し、service のターゲットは -preview と -prod で切り替わる点に注目。コードからは fetch のように呼ぶが、リクエストは内部でディスパッチされる：

// env.IMAGE_RESIZER is the service binding; this never hits the public internet.
const res = await env.IMAGE_RESIZER.fetch("https://internal/resize", {
  method: "POST",
  body: imageBytes,
});

本番環境のみのカスタムドメインルート

apex と www のドメインは custom_domain = true で production 環境にのみ割り当てる。こうすれば preview デプロイは生成された *.workers.dev の URL に留まり、本物のドメインを配信することはない：

[env.production]

# Custom-domain routes — production environment only.
[[env.production.routes]]
pattern = "example.com"
custom_domain = true

[[env.production.routes]]
pattern = "www.example.com"
custom_domain = true

custom_domain = true は、既存のゾーンのルートパターンに一致させるのではなく、そのホスト名の DNS レコードと TLS 証明書を Cloudflare が自動で作成・管理するよう指示する。

[env.preview]
routes = []