Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

設定

最終更新 Markdown で表示Agent セットアップ

Wrangler は任意で設定ファイルを使い、Worker の開発とデプロイの設定をカスタマイズします。

Wrangler の設定ファイルは、Worker 設定の 信頼できる情報源 として扱うのがベストプラクティスです。

Wrangler 設定のサンプル

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// Top-level configuration
	"name": "my-worker",
	"main": "src/index.js",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"workers_dev": false,
	"route": {
		"pattern": "example.org/*",
		"zone_name": "example.org",
	},
	"kv_namespaces": [
		{
			"binding": "<MY_NAMESPACE>",
			"id": "<KV_ID>",
		},
	],
	"env": {
		"staging": {
			"name": "my-worker-staging",
			"route": {
				"pattern": "staging.example.org/*",
				"zone_name": "example.org",
			},
			"kv_namespaces": [
				{
					"binding": "<MY_NAMESPACE>",
					"id": "<STAGING_KV_ID>",
				},
			],
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.js"
# Set this to today's date
compatibility_date = "2026-09-20"
workers_dev = false

[route]
pattern = "example.org/*"
zone_name = "example.org"

[[kv_namespaces]]
binding = "<MY_NAMESPACE>"
id = "<KV_ID>"

[env.staging]
name = "my-worker-staging"

  [env.staging.route]
  pattern = "staging.example.org/*"
  zone_name = "example.org"

  [[env.staging.kv_namespaces]]
  binding = "<MY_NAMESPACE>"
  id = "<STAGING_KV_ID>"

環境

Wrangler の environments を使い、Worker に異なる設定を定義できます。 デフォルト（トップレベル）の環境があり、名前付き環境を作って環境固有の設定を指定できます。

これらは [env.<name>] キーの下に定義します。たとえば [env.staging] です。プレビューやデプロイは、npx wrangler deploy --env staging のように wrangler コマンドの -e / --env フラグで行います。

大半のキーは継承可能です。トップレベルの設定を環境でも使えます。Bindings（vars や kv_namespaces など）は継承されません。明示的に定義する必要があります。

さらに、トップレベルにしか置けないキーもいくつかあります。

自動プロビジョニング

ベータ

Wrangler は、デプロイ時にリソースを自動でプロビジョニングできます。事前に作成しておく必要はありません。

現在、次のリソースに対応します。KV、R2、D1、Flagship、AI Search、Agent Memory、Dispatch Namespaces、Queues。

この機能を使うには、リソース ID を付けずに設定ファイルへバインディングを追加します。R2 の場合はバケット名も不要です。リソースは、Worker 名をプレフィックスとして作成されます。

{
	"kv_namespaces": [
		{
			"binding": "<MY_KV_NAMESPACE>",
		},
	],
}
[[kv_namespaces]]
binding = "<MY_KV_NAMESPACE>"

wrangler dev を実行すると、実行間で残るローカルリソースが自動作成されます。wrangler deploy を実行すると、リソースが作成され、その ID が設定ファイルへ書き戻されます。

ダッシュボードから（たとえば GitHub 経由で）リソース ID なしの Worker をデプロイした場合、リソースは作成されますが、ID はダッシュボードからのみ確認できます。現時点では、これらのリソース ID はリポジトリへ書き戻されません。

トップレベル専用キー

トップレベルキーは Worker 全体（したがってすべての環境）に適用されます。名前付き環境内では定義できません。

  • keep_vars boolean optional
    • デプロイ時に、ダッシュボードで設定した変数を Wrangler が保持するかどうか。信頼できる情報源 を参照してください。
  • send_metrics boolean optional
    • このプロジェクトについて、Wrangler が利用状況データを Cloudflare へ送るかどうか。デフォルトは true です。詳細は データポリシー ↗ を参照してください。
  • dependencies_instrumentation object optional
    • Worker バージョンのデプロイまたはアップロード時に、npm パッケージ依存関係の計測を設定します。デフォルトは有効です。
    • enabled boolean — Wrangler が npm パッケージ依存関係のメタデータ（パッケージ名とバージョン）を収集して送信するかどうか。デフォルトは true です。
  • site object optional deprecated
    • 詳細は下記の Workers Sites を参照してください。この方法より、Cloudflare Pages と Workers Assets が推奨されます。
    • Cloudflare Vite plugin ではサポートされません。

継承可能なキー

継承可能なキーはトップレベルで設定でき、環境固有の設定で継承（または上書き）できます。

  • name string required
    • Worker の名前。英数字（a、b、c など）とハイフン（-）のみです。アンダースコア（_）は使えません。Worker 名は最大 255 文字です。workers.dev サブドメイン を使う場合、名前は 63 文字以下で、先頭と末尾をハイフンにできません。
  • main string required
    • 実行される Worker のエントリポイントへのパスです。例: ./src/index.ts。
  • compatibility_date string required
    • yyyy-mm-dd 形式の日付です。Workers ランタイムのどのバージョンを使うかを決めます。Compatibility dates を参照してください。
  • account_id string optional
    • ゾーンに関連付けられたアカウントの ID です。アカウントが複数ある場合があるため、ゾーン / ルートを指定するときは、そのゾーン / ルートに紐づくアカウントの ID を使います。CLOUDFLARE_ACCOUNT_ID 環境変数でも指定できます。
  • compatibility_flags string[] optional
    • Workers ランタイムの今後の機能を有効にするフラグのリストです。通常は compatibility_date と一緒に使います。compatibility dates を参照してください。
  • workers_dev boolean optional
    • *.workers.dev サブドメインへの Worker デプロイを有効にします。scheduled イベント専用の Worker では false にできます。デフォルトは true です。ルートの種類 を参照してください。
  • preview_urls boolean optional
    • Preview URLs を使った Worker のテストを有効にします。デフォルトは workers_dev の値です。Preview URLs を参照してください。
  • route Route optional
    • Worker をデプロイするルートです。routes または route のどちらか一方だけが必要です。ルートの種類 を参照してください。
  • routes Route[] optional
    • Worker をデプロイするルートの配列です。routes または route のどちらか一方だけが必要です。ルートの種類 を参照してください。
  • tsconfig string optional
    • カスタム tsconfig へのパスです。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • triggers object optional
    • Worker の scheduled 関数を起動する cron 定義です。トリガー を参照してください。
  • rules Rule optional
    • どのモジュールを、どの型としてインポートするかを定義するルールの順序付きリストです。Text、Data、CompiledWasm モジュールを使う場合、または .js ファイルを CommonJS ではなく ESModule として扱いたい場合に指定します。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • build Build optional
    • Wrangler が Worker をビルドするときに実行するカスタムビルドステップを設定します。カスタムビルド を参照してください。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • no_bundle boolean optional
    • 内部ビルドステップをスキップし、Worker スクリプトを直接デプロイします。依存関係のないプレーンな JavaScript Worker が必要です。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • find_additional_modules boolean optional
    • true の場合、Wrangler は base_dir 以下のファイルツリーを走査します。 rules に一致するファイルは、デプロイする Worker に含まれます。 no_bundle が true のときはデフォルトで true、それ以外は false です。 Module 形式の Worker でのみ使えます（Service Worker 形式では使えません）。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • base_dir string optional
    • 追加ファイルを Worker デプロイに含めるとき（find_additional_modules 経由）、モジュールの rules を評価するディレクトリです。未指定の場合、Worker の main エントリポイントを含むディレクトリがデフォルトです。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • preserve_file_names boolean optional
    • Worker と一緒にバンドルする追加モジュールのファイル名を Wrangler が保持するかどうかを決めます。 デフォルトでは、ファイル名の先頭にコンテンツハッシュを付けます。 例: 34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico。
    • Cloudflare Vite plugin を使う場合は適用されません。
  • minify boolean optional
  • keep_names boolean optional
    • Wrangler は開発とデプロイで Worker コードの処理に esbuild を使います。このオプションでは、esbuild がコードに keepNames ↗ ロジックを適用するかどうかを指定できます。デフォルトは true です。
  • logpush boolean optional
    • Worker の Workers Trace Events Logpush を有効にします。このプロパティがあるスクリプトは、アカウントに設定された Workers Logpush ジョブが自動で取り込みます。デフォルトは false です。Workers Logpush を参照してください。
  • limits Limits optional
    • ランタイム実行に課す制限を設定します。Limits を参照してください。
  • observability object optional
    • Worker から出るテレメトリデータの自動オブザーバビリティ設定です。Observability を参照してください。
  • assets Assets optional
    • 配信する静的アセットを設定します。詳細は Assets を参照してください。
  • exports object optional
    • この Worker がエクスポートする Durable Object クラスと、そのライフサイクル状態（created、deleted、renamed、transferred、expecting-transfer）を宣言します。Durable Object class exports を参照してください。migrations とは排他です。
  • migrations object optional
    • Durable Object をクラス名からランタイム状態へ対応付ける、レガシーな命令的設定です。新しい Worker では exports を使います。Durable Object class migrations (legacy) を参照してください。
  • placement object optional
    • バックエンドサービスへのレイテンシを下げるため、Worker の実行場所を設定します。Placement を参照してください。
    • mode string — "smart" にすると、観測したレイテンシに基づき、バックエンドサービスの近くへ Worker を自動配置します。
    • region string — クラウドリージョン（例: "aws:us-east-1"、"gcp:europe-west1"、"azure:westeurope"）を指定し、そのリージョンのインフラ近くへ Worker を配置します。
    • host string — シングルホームのレイヤー 4 サービス向けにホスト名とポート（例: "my_database_host.com:5432"）を指定し、そのサービス近くへ Worker を配置します。
    • hostname string — シングルホームのレイヤー 7 サービス向けにホスト名（例: "my_api_server.com"）を指定し、そのサービス近くへ Worker を配置します。

継承されないキー

継承されないキーはトップレベルで設定できますが、環境には継承されません。各環境で指定する必要があります。

  • define Record<string, string> optional
    • Worker のデプロイ時に置換する値のマップです。
    • Cloudflare Vite plugin を使う場合、define は Vite の define ↗ に置き換わります。
  • vars object optional
    • Worker のデプロイ時に設定する環境変数のマップです。Environment variables を参照してください。
  • durable_objects object optional
    • Worker がバインドする Durable Objects のリストです。Durable Objects を参照してください。
  • kv_namespaces object optional
    • Worker がバインドする KV 名前空間のリストです。KV namespaces を参照してください。
  • r2_buckets object optional
    • Worker がバインドする R2 バケットのリストです。R2 buckets を参照してください。
  • ai_search_namespaces object optional
    • Worker がバインドする AI Search 名前空間のリストです。AI Search namespaces を参照してください。
  • ai_search object optional
    • デフォルト名前空間内の既存インスタンスへ直接バインドする AI Search インスタンスバインディングのリストです。AI Search instances を参照してください。
  • vectorize object optional
    • Worker がバインドする Vectorize インデックスのリストです。Vectorize indexes を参照してください。
  • services object optional
    • Worker がバインドするサービスバインディングのリストです。service bindings を参照してください。
  • queues object optional
    • Worker がバインドする Queue のプロデューサーとコンシューマーのリストです。Queues を参照してください。
  • workflows object optional
    • Worker がバインドする Workflows のリストです。Workflows を参照してください。
  • tail_consumers object optional
    • Worker がデータを送る Tail Workers のリストです。Tail Workers を参照してください。
  • secrets object optional
    • Worker が必要とするシークレット名を宣言します。ローカル開発とデプロイ時の検証、および型生成の信頼できる情報源として使います。Secrets を参照してください。
    • required string[] optional — Worker のデプロイに必須のシークレット名のリストです。
  • secrets_store_secrets object optional
    • Worker がバインドする Secrets Store バインディングのリストです。Secrets Store を参照してください。

ルートの種類

ルート には 3 種類あります。Custom Domains、routes、workers.dev です。

Custom Domains

Custom Domains を使うと、DNS 設定の変更や証明書管理なしで、Worker をドメインまたはサブドメインへ接続できます。

  • pattern string required
    • Worker を実行するパターンです。例: "example.com"。
  • custom_domain boolean optional
    • Worker をルートではなく Custom Domain にするかどうか。デフォルトは false です。

例:

{
	"routes": [
		{
			"pattern": "shop.example.com",
			"custom_domain": true,
		},
	],
}
[[routes]]
pattern = "shop.example.com"
custom_domain = true

Routes

Routes は、URL パターンを Worker へ対応付けます。ルートはゾーン ID ルート、ゾーン名ルート、またはシンプルルートとして設定できます。

Zone ID ルート

  • pattern string required
    • Worker を実行できるパターンです。例: "example.com/*"。
  • zone_id string required

例:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_id": "<YOUR_ZONE_ID>",
		},
	],
}
[[routes]]
pattern = "subdomain.example.com/*"
zone_id = "<YOUR_ZONE_ID>"

Zone name ルート

  • pattern string required
    • Worker を実行するパターンです。例: "example.com/*"。
  • zone_name string required
    • pattern が関連付けられたゾーンの名前です。API トークンを使う場合は Account スコープが必要です。

例:

{
	"routes": [
		{
			"pattern": "subdomain.example.com/*",
			"zone_name": "example.com",
		},
	],
}
[[routes]]
pattern = "subdomain.example.com/*"
zone_name = "example.com"

シンプルルート

パターンだけが必要なシンプルなルートです。

例:

{
	"route": "example.com/*",
}
route = "example.com/*"

workers.dev

Cloudflare Workers アカウントには、Cloudflare ダッシュボードで設定できる workers.dev サブドメインが付きます。

  • workers_dev boolean optional
    • Worker をカスタム workers.dev アカウントサブドメインで実行するかどうか。デフォルトは true です。
{
	"workers_dev": false,
}
workers_dev = false

トリガー

トリガーでは、Worker の scheduled 関数を呼び出す cron 式を定義できます。サポートされる cron 式 を参照してください。

  • crons string[] required
    • cron 式の配列です。
    • Cron Trigger を無効にするには、crons = [] を設定します。crons キーをコメントアウトしても Cron Trigger は無効になりません。

例:

{
	"triggers": {
		"crons": ["* * * * *"],
	},
}
[triggers]
crons = [ "* * * * *" ]

Observability

Observability 設定を使うと、Cloudflare Workers から出るログデータを自動で取り込み、保存、フィルタ、分析できます。Cloudflare Worker のダッシュボードから直接操作します。

  • enabled boolean required
    • Worker で true にすると、その Worker のログが永続化されます。新しい Worker ではデフォルトで true です。
  • head_sampling_rate number optional
    • 0 から 1 の数値です。0 は 100 件中 0 件のリクエストが記録され、1 はすべてのリクエストが記録されます。head_sampling_rate を未指定の場合、デフォルト値は 1（100%）です。ヘッドベースサンプリング の詳細を参照してください。

例:

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.1, // 10% of requests are logged
	},
}
[observability]
enabled = true
head_sampling_rate = 0.1

カスタムビルド

Worker のデプロイ前に実行するカスタムビルドステップを設定できます。カスタムビルド を参照してください。

  • command string optional
    • Worker のビルドに使うコマンドです。Linux と macOS では sh シェル、Windows では cmd シェルで実行されます。シェル演算子 && と || を使えます。
  • cwd string optional
    • コマンドを実行するディレクトリです。
  • watch_dir string | string[] optional
    • wrangler dev 使用時に変更を監視するディレクトリです。デフォルトは現在の作業ディレクトリです。

例:

{
	"build": {
		"command": "npm run build",
		"cwd": "build_cwd",
		"watch_dir": "build_watch_dir",
	},
}
[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"

Limits

ランタイムでの Worker の動作に制限を課せます。制限は Standard Usage Model でのみサポートされます。 制限は Cloudflare のネットワークへデプロイしたときだけ適用され、ローカル開発では適用されません。CPU 制限の上限は 300,000 ミリ秒（5 分）です。

各 isolate には、Worker が設定した上限をたまに超える場合に備えた余裕があります。上限を継続的に超えるようになると、設定した上限に従って実行が打ち切られます。


  • cpu_ms number optional
    • 1 回の呼び出しで許可される最大 CPU 時間（ミリ秒）です。
  • subrequests number optional
    • 1 回の呼び出しで許可される最大サブリクエスト数です。無料アカウントのデフォルトは 50、有料アカウントのデフォルトは 10,000 です。無料アカウントの上限は 50、有料アカウントの上限は 10,000,000 です。詳細は サブリクエスト制限 を参照してください。

例:

{
	"limits": {
		"cpu_ms": 100,
		"subrequests": 150,
	},
}
[limits]
cpu_ms = 100
subrequests = 150

Bindings

Browser Run

Workers Browser Run API を使うと、ヘッドレスブラウザーインスタンスをプログラムから操作し、アプリケーションや製品向けの自動化フローを作れます。

browser binding は、専用の Chromium ブラウザーインスタンスとやり取りするための認証済みエンドポイントを Worker に提供します。

  • binding string required
    • browser binding を参照するバインディング名です。設定した文字列が、Worker 内でこのヘッドレスブラウザーを参照するために使われます。バインディングは 有効な JavaScript 変数名 ↗ である必要があります。例: binding = "HEAD_LESS" と binding = "simulatedBrowser" はどちらも有効な名前です。

例:

{
	"browser": {
		"binding": "<BINDING_NAME>",
	},
}
[browser]
binding = "<BINDING_NAME>"

D1 databases

D1 は Cloudflare のサーバーレス SQL データベースです。Worker は、D1 Workers Binding API 用に各データベースへの binding を作り、D1 データベースをクエリできます。

D1 データベースを Worker にバインドするには、次のオブジェクトの配列を [[d1_databases]] キーに割り当てます。

  • binding string required

    • D1 データベースを参照するバインディング名です。設定した文字列が、Worker 内でこのデータベースを参照するために使われます。バインディングは 有効な JavaScript 変数名 ↗ である必要があります。例: binding = "MY_DB" と binding = "productionDB" はどちらも有効な名前です。

  • database_name string required

    • データベースの名前です。データベースを区別するための人が読める名前で、最初に作成したときに設定します。

  • database_id string required

    • データベースの ID です。最初に wrangler d1 create を使うとき、または wrangler d1 list を呼ぶときに確認でき、データベースを一意に識別します。

  • preview_database_id string optional

    • この D1 データベースのプレビュー ID です。指定した場合、wrangler dev はこの ID を使います。未指定の場合は database_id を使います。本番データベースを避けるため、wrangler dev --remote を使うときに推奨されます。

  • migrations_dir string optional

    • マイグレーションファイルを含むマイグレーションディレクトリです。デフォルトでは、wrangler d1 migrations create は migrations というフォルダーを作ります。マイグレーションファイルを含む別のフォルダーを指定するには migrations_dir を使います（モノレポ構成で、アプリ / パッケージ横断で 1 つの D1 インスタンスを使う場合など）。
    • 詳細は D1 Wrangler migrations コマンド と D1 migrations を参照してください。

  • migrations_pattern string optional

    • マイグレーションファイルを見つけるための glob パターン（Wrangler 設定ファイルからの相対）です。デフォルトは migrations/*.sql です。
    • Drizzle などの ORM が作る入れ子レイアウト（例: migrations/*/migration.sql）にオプトインするために使います。
    • migrations_pattern を設定する場合は migrations_dir も設定する必要があり、migrations_pattern は migrations_dir の値で始まる必要があります。各マイグレーションは、migrations_dir からの相対パスとしてマイグレーションテーブルに記録されます。

例:

{
	"d1_databases": [
		{
			"binding": "<BINDING_NAME>",
			"database_name": "<DATABASE_NAME>",
			"database_id": "<DATABASE_ID>",
		},
	],
}
[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"

Dispatch namespace bindings（Workers for Platforms）

Dispatch namespace bindings は、dynamic dispatch Worker と dispatch namespace の通信を可能にします。Dispatch namespace bindings は Workers for Platforms で使います。Workers for Platforms は、顧客に代わってサーバーレス関数をプログラムからデプロイするのに役立ちます。

  • binding string required
    • バインディング名です。設定した文字列が、Worker 内でこのデータベースを参照するために使われます。バインディングは 有効な JavaScript 変数名 ↗ である必要があります。例: binding = "MY_NAMESPACE" と binding = "productionNamespace" はどちらも有効な名前です。
  • namespace string required
  • outbound object optional 
{
	"dispatch_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "<NAMESPACE_NAME>",
			"outbound": {
				"service": "<WORKER_NAME>",
				"parameters": ["params_object"],
			},
		},
	],
}
[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"

  [dispatch_namespaces.outbound]
  service = "<WORKER_NAME>"
  parameters = [ "params_object" ]

Durable Objects

Durable Objects は、Workers プラットフォーム向けに低レイテンシの調整と一貫したストレージを提供します。

Durable Objects を Worker にバインドするには、次のオブジェクトの配列を durable_objects.bindings キーに割り当てます。

  • name string required
    • Durable Object を参照するバインディング名です。
  • class_name string required
    • Durable Object のエクスポートされたクラス名です。
  • script_name string optional
    • Durable Object が定義されている Worker の名前です。この Worker の外部にある場合に使います。ローカル開発とリモート開発の両方で使えます。ローカル開発では、外部 Worker を別プロセス（wrangler dev）で実行する必要があります。リモート開発では、適切なリモートバインディングを使う必要があります。
  • environment string optional
    • バインドする script_name の環境です。

例:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "<BINDING_NAME>",
				"class_name": "<CLASS_NAME>",
			},
		],
	},
}
[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

Exports

exports フィールドは、この Worker がエクスポートする Durable Object クラスと、そのライフサイクル状態を宣言します。Durable Object class exports を参照してください。

exports の各エントリは Durable Object クラス名をキーにします。各エントリのフィールドは次のとおりです。

  • type string required
    • Durable Object クラスのエントリでは、これを "durable-object" に設定します。
  • state string optional
    • ライフサイクル状態です。"created"（デフォルト — 稼働中のクラス）、"deleted"、"renamed"、"transferred"、"expecting-transfer" のいずれかです。
  • storage string conditional
    • state が "created" または "expecting-transfer" のときに必須です。"sqlite"（推奨。新しい名前空間では必須）または "legacy-kv"（既存のキーバリューバックエンド名前空間のみ）のいずれかです。
  • renamed_to string conditional
    • state が "renamed" のときに必須です。移動先のクラス名で、同じ exports マップ内に稼働中のエントリとしても存在する必要があります。
  • transferred_to string conditional
    • state が "transferred" のときに必須です。名前空間を受け取る対象 Worker の名前です。
  • transfer_from string conditional
    • state が "expecting-transfer" のときに必須です。名前空間の転送元となるソース Worker の名前です。

例:

{
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"OldClass": {
			"type": "durable-object",
			"state": "deleted",
		},
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName",
		},
		"NewName": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}
[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

[exports.OldClass]
type = "durable-object"
state = "deleted"

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

Migrations

レガシーな migrations 配列を使う Worker で Durable Object クラスを変更する場合は、マイグレーションが必要です。Durable Object class migrations (legacy) を参照してください。

  • tag string required
    • このマイグレーションの一意な識別子です。
  • new_sqlite_classes string[] optional
    • SQLite ストレージバックエンドで定義する新しい Durable Object クラスです。
  • new_classes string[] optional
    • レガシーなキーバリューストレージバックエンドで定義する新しい Durable Object クラスです。
  • renamed_classes {from: string, to: string}[] optional
    • 名前を変更する Durable Object クラスです。
  • deleted_classes string[] optional
    • 削除する Durable Object クラスです。
  • transferred_classes {from: string, from_script: string, to: string}[] optional
    • 別の Worker から転送する Durable Object クラスです。

例:

{
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": [
				// Array of new classes
				"DurableObjectExample",
			],
		},
		{
			"tag": "v2", // Should be unique for each entry
			"renamed_classes": [
				// Array of rename directives
				{
					"from": "DurableObjectExample",
					"to": "UpdatedName",
				},
			],
			"deleted_classes": [
				// Array of deleted class names
				"DeprecatedClass",
			],
		},
	],
}
[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectExample" ]

[[migrations]]
tag = "v2"
deleted_classes = [ "DeprecatedClass" ]

  [[migrations.renamed_classes]]
  from = "DurableObjectExample"
  to = "UpdatedName"

Email bindings

Email Routing で検証済みのメールアドレスへ、Worker から Worker のアクティビティに関するメールを送れます。特定の種類のイベントが起きたときに知らせたい場合などに便利です。

メールアドレスを Worker にバインドする前に、Email Routing を有効 にし、検証済みメールアドレス を少なくとも 1 つ用意する必要があります。 次に、必要なメールバインディングの種類を持つオブジェクト（send_email）へ配列を割り当てます。

Wrangler ファイルには、1 つ以上の種類のバインディングを追加できます。ただし、各属性はそれぞれ別の行に書く必要があります。

{
	"send_email": [
		{
			"name": "<NAME_FOR_BINDING1>"
		},
		{
			"name": "<NAME_FOR_BINDING2>",
			"destination_address": "<YOUR_EMAIL>@example.com"
		},
		{
			"name": "<NAME_FOR_BINDING3>",
			"allowed_destination_addresses": [
				"<YOUR_EMAIL>@example.com",
				"<YOUR_EMAIL2>@example.com"
			]
		}
	]
}
[[send_email]]
name = "<NAME_FOR_BINDING1>"

[[send_email]]
name = "<NAME_FOR_BINDING2>"
destination_address = "<YOUR_EMAIL>@example.com"

[[send_email]]
name = "<NAME_FOR_BINDING3>"
allowed_destination_addresses = [ "<YOUR_EMAIL>@example.com", "<YOUR_EMAIL2>@example.com" ]

Environment variables

Environment variables は、テキスト文字列または JSON 値を Worker に付けるバインディングの一種です。

例:

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker-dev",
	"vars": {
		"API_HOST": "example.com",
		"API_ACCOUNT_ID": "example_user",
		"SERVICE_X_DATA": {
			"URL": "service-x-api.dev.example",
			"MY_ID": 123
		}
	}
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"

[vars]
API_HOST = "example.com"
API_ACCOUNT_ID = "example_user"

  [vars.SERVICE_X_DATA]
  URL = "service-x-api.dev.example"
  MY_ID = 123

Hyperdrive

Hyperdrive バインディングを使うと、Worker 内から任意の Postgres データベースとやり取りし、クエリできます。

  • binding string required
    • バインディング名です。
  • id string required
    • Hyperdrive 設定の ID です。

例:

{
	// required for database drivers to function
	"compatibility_flags": ["nodejs_compat_v2"],
	"hyperdrive": [
		{
			"binding": "<BINDING_NAME>",
			"id": "<ID>",
		},
	],
}
compatibility_flags = [ "nodejs_compat_v2" ]

[[hyperdrive]]
binding = "<BINDING_NAME>"
id = "<ID>"

Images

Cloudflare Images を使うと、リモートソースに保存された画像の最適化、リサイズ、加工のための変換リクエストを送れます。

Images を Worker にバインドするには、次のオブジェクトの配列を images キーに割り当てます。

binding（必須）。Images API を参照するバインディング名です。

{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}
[images]
binding = "IMAGES"

KV namespaces

Workers KV は、グローバルで低レイテンシのキーバリューデータストアです。少数の中央データセンターにデータを保存し、アクセス後に Cloudflare のデータセンターへキャッシュします。

KV 名前空間を Worker にバインドするには、次のオブジェクトの配列を kv_namespaces キーに割り当てます。

  • binding string required
    • KV 名前空間を参照するバインディング名です。
  • id string required
    • KV 名前空間の ID です。
  • preview_id string optional
    • この KV 名前空間のプレビュー ID です。リモートリソースに対して開発する wrangler dev --remote を使うときは、このオプションが 必須 です（remote bindings では不要です）。ローカル開発では任意です。wrangler dev はこの ID を KV 名前空間に使います。未指定の場合、wrangler dev は id を使います。

例:

{
	"kv_namespaces": [
		{
			"binding": "<BINDING_NAME1>",
			"id": "<NAMESPACE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"id": "<NAMESPACE_ID2>",
		},
	],
}
[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"

[[kv_namespaces]]
binding = "<BINDING_NAME2>"
id = "<NAMESPACE_ID2>"

AI Search namespaces

AI Search は Cloudflare のマネージド検索サービスです。名前空間 は AI Search インスタンスの論理グループです。このバインディングは、名前空間内のすべてのインスタンスへのフルアクセスを与えます。

AI Search 名前空間を Worker にバインドするには、次のオブジェクトの配列を ai_search_namespaces キーに割り当てます。

  • binding string required
    • AI Search 名前空間を参照するバインディング名です。
  • namespace string required
    • AI Search 名前空間の名前です。すべてのアカウントに default 名前空間が自動作成されます。名前空間が存在しない場合、Wrangler はデプロイ時に作成します。

例:

{
	"ai_search_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"namespace": "default",
		},
	],
}
[[ai_search_namespaces]]
binding = "<BINDING_NAME>"
namespace = "default"

AI Search instances

デフォルト名前空間 内の既存 AI Search インスタンスへ直接バインドするには、次のオブジェクトの配列を ai_search キーに割り当てます。このバインディングは list()、create()、delete() などの名前空間レベルの操作には対応しません。

  • binding string required
    • AI Search インスタンスを参照するバインディング名です。
  • instance_name string required
    • AI Search インスタンスの名前です。デプロイ時にデフォルト名前空間に存在する必要があります。

例:

{
	"ai_search": [
		{
			"binding": "<BINDING_NAME>",
			"instance_name": "<INSTANCE_NAME>",
		},
	],
}
[[ai_search]]
binding = "<BINDING_NAME>"
instance_name = "<INSTANCE_NAME>"

Queues

Queues は Cloudflare のグローバルメッセージキューイングサービスです。配信保証 と メッセージのバッチ処理 を提供します。Workers でキューとやり取りするには、キューへメッセージを送るプロデューサー Worker と、キューからメッセージのバッチを取り出すコンシューマー Worker が必要です。1 つの Worker が複数の Queues へプロデュースし、複数の Queues からコンシュームできます。

プロデューサー Worker に Queues をバインドするには、次のオブジェクトの配列を [[queues.producers]] キーに割り当てます。

  • queue string required
    • キューの名前です。Cloudflare ダッシュボードで使います。
  • binding string required
    • Worker 内でキューを参照するバインディング名です。バインディングは 有効な JavaScript 変数名 ↗ である必要があります。例: binding = "MY_QUEUE" と binding = "productionQueue" はどちらも有効な名前です。
  • delivery_delay number optional

例:

{
	"queues": {
		"producers": [
			{
				"binding": "<BINDING_NAME>",
				"queue": "<QUEUE_NAME>",
				"delivery_delay": 60, // Delay messages by 60 seconds before they are delivered to a consumer
			},
		],
	},
}
[[queues.producers]]
binding = "<BINDING_NAME>"
queue = "<QUEUE_NAME>"
delivery_delay = 60

コンシューマー Worker に Queues をバインドするには、次のオブジェクトの配列を [[queues.consumers]] キーに割り当てます。

  • queue string required
    • キューの名前です。Cloudflare ダッシュボードで使います。
  • max_batch_size number optional
    • 各バッチで許可される最大メッセージ数です。
  • max_batch_timeout number optional
    • バッチをコンシューマー Worker へ送る前に、メッセージがバッチを満たすまで待つ最大秒数です。
  • max_retries number optional
    • メッセージが失敗したとき、または retryAll() が呼ばれたときの最大リトライ回数です。
  • dead_letter_queue string optional
    • 少なくとも max_retries 回処理に失敗したメッセージを送る、別のキューの名前です。
    • dead_letter_queue が未定義の場合、繰り返し処理に失敗したメッセージは破棄されます。
    • 指定した名前のキューがない場合は自動作成されます。
  • max_concurrency number optional
    • 同時に実行できるコンシューマーの最大数です。未設定の場合、呼び出し数は 現在サポートされる上限 までスケールします。
    • コンシューマーのオートスケール（特にメッセージ再試行時）については Consumer concurrency を参照してください。
  • retry_delay number optional

例:

{
	"queues": {
		"consumers": [
			{
				"queue": "my-queue",
				"max_batch_size": 10,
				"max_batch_timeout": 30,
				"max_retries": 10,
				"dead_letter_queue": "my-queue-dlq",
				"max_concurrency": 5,
				"retry_delay": 120, // Delay retried messages by 2 minutes before re-attempting delivery
			},
		],
	},
}
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30
max_retries = 10
dead_letter_queue = "my-queue-dlq"
max_concurrency = 5
retry_delay = 120

R2 buckets

Cloudflare R2 Storage を使うと、一般的なクラウドストレージサービスに伴う高額なエグレス帯域料金なしで、大量の非構造化データを保存できます。

R2 バケットを Worker にバインドするには、次のオブジェクトの配列を r2_buckets キーに割り当てます。

  • binding string required
    • R2 バケットを参照するバインディング名です。
  • bucket_name string required
    • この R2 バケットの名前です。
  • jurisdiction string optional
    • 管轄が指定されている場合、この R2 バケットがある管轄です。Jurisdictional Restrictions を参照してください。
  • preview_bucket_name string optional
    • この R2 バケットのプレビュー名です。指定した場合、wrangler dev はこの名前を R2 バケットに使います。未指定の場合は bucket_name を使います。wrangler dev --remote を使うときはこのオプションが必須です（remote bindings では不要です）。

例:

{
	"r2_buckets": [
		{
			"binding": "<BINDING_NAME1>",
			"bucket_name": "<BUCKET_NAME1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"bucket_name": "<BUCKET_NAME2>",
		},
	],
}
[[r2_buckets]]
binding = "<BINDING_NAME1>"
bucket_name = "<BUCKET_NAME1>"

[[r2_buckets]]
binding = "<BINDING_NAME2>"
bucket_name = "<BUCKET_NAME2>"

Vectorize indexes

Vectorize index を使うと、セマンティック検索、分類、その他のベクトル検索用途向けにベクトル埋め込みを挿入してクエリできます。

Vectorize インデックスを Worker にバインドするには、次のオブジェクトの配列を vectorize キーに割り当てます。

  • binding string required
    • Worker コードからバインドされたインデックスを参照するバインディング名です。
  • index_name string required
    • バインドするインデックスの名前です。

例:

{
	"vectorize": [
		{
			"binding": "<BINDING_NAME>",
			"index_name": "<INDEX_NAME>",
		},
	],
}
[[vectorize]]
binding = "<BINDING_NAME>"
index_name = "<INDEX_NAME>"

Service bindings

サービスバインディングを使うと、インターネットを経由せずに別の Worker へ HTTP リクエストを送れます。リクエストはすぐに下流の Worker を呼び出すため、サードパーティサービスへのリクエストと比べてレイテンシが下がります。About Service Bindings を参照してください。

ほかの Worker を Worker にバインドするには、次のオブジェクトの配列を services キーに割り当てます。

  • binding string required
    • バインドした Worker を参照するバインディング名です。
  • service string required
    • Worker の名前です。
    • 特定の environment の Worker にバインドするには、Worker 名のあとに環境名を付ける必要があります。形式は <worker-name>-<environment-name> です。たとえば staging 環境の worker-name という Worker にバインドする場合、service は worker-name-staging にします。
  • entrypoint string optional
    • バインドする entrypoint の名前です。entrypoint を指定しない場合は、Worker のデフォルトエクスポートが使われます。

例:

{
	"services": [
		{
			"binding": "<BINDING_NAME>",
			"service": "<WORKER_NAME>",
			"entrypoint": "<ENTRYPOINT_NAME>",
		},
	],
}
[[services]]
binding = "<BINDING_NAME>"
service = "<WORKER_NAME>"
entrypoint = "<ENTRYPOINT_NAME>"

Static assets

Assets を参照してください。

Analytics Engine Datasets

Workers Analytics Engine は、Workers からの分析、オブザーバビリティ、データロギングを提供します。Worker バインディングへデータポイントを書き込み、SQL API でデータをクエリします。

Analytics Engine データセットを Worker にバインドするには、次のオブジェクトの配列を analytics_engine_datasets キーに割り当てます。

  • binding string required
    • データセットを参照するバインディング名です。
  • dataset string optional
    • 書き込み先のデータセット名です。未指定の場合、バインディングと同じ名前がデフォルトになります。

例:

{
	"analytics_engine_datasets": [
		{
			"binding": "<BINDING_NAME>",
			"dataset": "<DATASET_NAME>",
		},
	],
}
[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

mTLS Certificates

クライアント認証が必要なオリジンと通信するため、Worker はサブリクエストで mTLS 用の証明書を提示できます。Wrangler は、これらの証明書のアップロードと管理に mtls-certificate コマンド を提供します。

Worker 向けの mTLS 証明書への binding を作るには、次の形のオブジェクト配列を mtls_certificates キーに割り当てます。

  • binding string required
    • 証明書を参照するバインディング名です。
  • certificate_id string required
    • 証明書の ID です。Wrangler は mtls-certificate upload と mtls-certificate list コマンドでこれを表示します。

mTLS 証明書バインディングを含む Wrangler 設定ファイルの例です。

{
	"mtls_certificates": [
		{
			"binding": "<BINDING_NAME1>",
			"certificate_id": "<CERTIFICATE_ID1>",
		},
		{
			"binding": "<BINDING_NAME2>",
			"certificate_id": "<CERTIFICATE_ID2>",
		},
	],
}
[[mtls_certificates]]
binding = "<BINDING_NAME1>"
certificate_id = "<CERTIFICATE_ID1>"

[[mtls_certificates]]
binding = "<BINDING_NAME2>"
certificate_id = "<CERTIFICATE_ID2>"

mTLS 証明書バインディングは、ランタイムで fetch メソッド 経由で保護されたオリジンと通信するために使えます。

Workers AI

Workers AI を使うと、自分のコードから Cloudflare ネットワーク上で機械学習モデルを実行できます。Workers、Pages、または REST API 経由のどこからでも使えます。

ほかのバインディングと異なり、このバインディングは Worker プロジェクトあたり 1 つの AI バインディングに制限されます。

  • binding string required
    • バインディング名です。

例:

{
	"ai": {
		"binding": "AI", // available in your Worker code on `env.AI`
	},
}
[ai]
binding = "AI"

Workflows

Workflows を使うと、Workers プラットフォーム上で耐久性のある多段階アプリケーションを構築できます。Workflow バインディングにより、Worker からプログラムで Workflow インスタンスを作成・管理できます。

Workflows を Worker にバインドするには、次のオブジェクトの配列を workflows キーに割り当てます。

  • binding string required
    • Worker 内で Workflow を参照するバインディング名です。バインディングは 有効な JavaScript 変数名 ↗ である必要があります。例: binding = "MY_WORKFLOW" は有効な名前です。
  • name string required
    • Workflow の名前です。
  • class_name string required
    • エクスポートされた Workflow クラスの名前です。class_name は、Worker コードからエクスポートした Workflow クラス名と一致する必要があります。
  • script_name string optional
    • Workflow クラスが定義されている Worker スクリプトの名前です。バインディングを設定する Worker と異なる Worker に Workflow がある場合にのみ必要です。
  • schedules string[] optional
    • この Workflow の新しいインスタンスを自動作成する cron スケジュールのリストです。
    • トップレベルの triggers.crons と別の scheduled ハンドラーを定義せずに、定期的な間隔で Workflow を実行したいときに使います。
    • Workflow スケジュールに対応する Wrangler リリースを使います。ローカルスキーマが schedules を認識しない場合は、先に Wrangler を更新します。

例:

{
	"workflows": [
		{
			"binding": "<BINDING_NAME>",
			"name": "<WORKFLOW_NAME>",
			"class_name": "<CLASS_NAME>",
		},
	],
}
[[workflows]]
binding = "<BINDING_NAME>"
name = "<WORKFLOW_NAME>"
class_name = "<CLASS_NAME>"

Assets

静的アセット を使うと、Workers 上でフロントエンドウェブサイトを実行できます。アセットのディレクトリ、任意のランタイムバインディング、ルーティング設定オプションを設定できます。

Worker あたり設定できるアセットのコレクションは 1 つだけです。

次のオプションは assets キーの下で使えます。

  • directory string optional
    • 配信する静的アセットのフォルダーです。
    • Cloudflare Vite plugin を使う場合は不要です。プラグインはクライアントのビルド出力を自動で指します。
  • binding string optional
    • アセットを参照するバインディング名です。任意で、main で Worker スクリプトが設定されているときだけ役立ちます。
  • run_worker_first boolean | string[] optional, defaults to false
    • 静的アセットを直接取得するか、Worker スクリプトを呼び出すかを制御します。boolean（true / false）か、glob パターン（*）と例外パターン（! プレフィックス）に対応したルートパターン文字列の配列です。パターンは / または !/ で始まる必要があります。最大 100 エントリまでです（重複も上限に数えます）。run_worker_first 使用時のアセット取得の詳細を参照してください。
  • html_handling: "auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none" optional, defaults to "auto-trailing-slash"
    • HTML コンテンツ向けリクエストのリダイレクトとリライトを決めます。各オプションの詳細は assets routing を参照してください。
  • not_found_handling: "single-page-application" | "404-page" | "none" optional, defaults to "none"
    • アセットに対応しないリクエストの扱いを決めます。ルーティング動作 の各オプションを参照してください。

例:

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"html_handling": "force-trailing-slash",
		"not_found_handling": "404-page",
	},
}
[assets]
directory = "./public"
binding = "ASSETS"
html_handling = "force-trailing-slash"
not_found_handling = "404-page"

run_worker_first をルートパターンの配列で設定することもできます。

{
	"assets": {
		"directory": "./public",
		"binding": "ASSETS",
		"run_worker_first": [
			"/api/*", // API calls go to Worker first
			"!/api/docs/*", // EXCEPTION: For /api/docs/*, try static assets first
		],
	},
}
[assets]
directory = "./public"
binding = "ASSETS"
run_worker_first = [ "/api/*", "!/api/docs/*" ]

Containers

containers フィールドを使い、Worker と一緒に実行する Containers を定義できます。

次のオプションが使えます。

  • image string required
    • コンテナに使うイメージです。Dockerfile へのローカルパス（この場合 wrangler deploy がイメージをビルドしてプッシュします）か、イメージ参照です。対応レジストリは Cloudflare Registry、Docker Hub、Amazon ECR、Google Artifact Registry です。詳細は Image Management を参照してください。
  • class_name string required
    • 対応する Durable Object クラス名です。これにより、この Durable Object はコンテナ対応 Durable Object になり、各インスタンスがコンテナを制御できます。詳細は Durable Object Container Methods を参照してください。
  • instance_type string optional
    • コンテナのインスタンスタイプです。コンテナインスタンスに与えるメモリ、CPU、ディスク量を決めます。現在のオプションは "lite"、"basic"、"standard-1"、"standard-2"、"standard-3"、"standard-4" です。デフォルトは "lite" です。詳細は インスタンスタイプのドキュメント を参照してください。
    • カスタムインスタンスタイプを指定する場合は カスタムインスタンスタイプ を参照してください。
  • max_instances string optional
    • 任意の時点で同時実行したいコンテナインスタンスの最大数です。停止中のコンテナはこの数に含まれません。全体ではこの数より多くのコンテナインスタンスがあってもかまいませんが、同時にアクティブに実行できるのはこの数までです。コンテナ開始リクエストがこの上限を超えると、そのリクエストはエラーになります。
    • デフォルトは 20 です。
    • この値は、Cloudflare のネットワーク上の本番実行時にのみ適用されます。ローカル開発ではこの制限は適用されないため、指定より多くのインスタンスを実行できます。
  • name string optional
    • コンテナの名前です。識別子として使います。デフォルトは Worker 名、クラス名、環境の組み合わせです。
  • image_build_context string optional
    • アプリケーションのビルドコンテキストです。デフォルトは image のディレクトリです。
  • image_vars Record<string, string> optional
  • rollout_active_grace_period number optional
    • ロールアウト 中に、コンテナインスタンスが置き換え可能になるまでに Durable Object へ接続済みである必要がある最小秒数です。デフォルトは 0 です。--containers-rollout=immediate でも適用されます。
  • rollout_step_percentage number | number[] optional
    • 各 ロールアウト ステップで更新するコンテナインスタンスの割合です。単一の数値はそのステップサイズ（5、10、20、25、50、または 100）を使います。配列は 10 から 100 までの昇順の整数値を含み、100 で終わり、最大 10 エントリ、かつ max_instances より多くない必要があります。値は累積です。max_instances が未指定または 2 未満の場合のデフォルトは 100、それ以外のデフォルトは [10, 100] です。1 回のデプロイでは --containers-rollout=immediate で上書きできます（単一の 100% ステップ。猶予期間は上書きしません）。
  • ssh object optional
    • Wrangler 経由の SSH 設定です。SSH を参照してください。
  • wrangler_ssh object optional deprecated, use `ssh`
    • ssh の非推奨エイリアスです。後方互換のためまだサポートされます。
  • authorized_keys object[] optional
    • Container の authorized_keys ファイルへ追加する公開鍵です。
  • constraints object optional
  • constraints.regions string[] optional
    • コンテナの配置を特定の地理的リージョンに制限します。有効な値: "ENAM"、"WNAM"、"EEUR"、"WEUR"、"APAC"、"SAM"、"ME"、"OC"、"AFR"。
  • constraints.jurisdiction string optional
    • コンテナをコンプライアンス境界に制限します。有効な値: "eu"、"fedramp"。
{
	"containers": [
		{
			"class_name": "MyContainer",
			"image": "./Dockerfile",
			"max_instances": 10,
			"instance_type": "basic", // Optional, defaults to "lite"
			"image_vars": {
				"FOO": "BAR",
			},
			"constraints": {
				"regions": ["ENAM", "WNAM"],
				"jurisdiction": "fedramp",
			},
		},
	],
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_CONTAINER",
				"class_name": "MyContainer",
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			"new_sqlite_classes": ["MyContainer"],
		},
	],
}
[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
max_instances = 10
instance_type = "basic"

  [containers.image_vars]
  FOO = "BAR"

  [containers.constraints]
  regions = [ "ENAM", "WNAM" ]
  jurisdiction = "fedramp"

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyContainer" ]

カスタムインスタンスタイプ

名前付きインスタンスタイプ の代わりに、vCPU、メモリ、ディスクを個別に設定してカスタムインスタンスタイプを指定できます。 カスタムインスタンスタイプの制約は 制限のドキュメント を参照してください。

次のオプションが使えます。

  • vcpu number optional
    • コンテナが使う vCPU です。デフォルトは 0.0625（1/16 vCPU）です。
  • memory_mib number optional
    • コンテナが使うメモリ（MiB）です。デフォルトは 256 です。
  • disk_mb number optional
    • コンテナが使うディスク（MB）です。デフォルトは 2000（2GB）です。
{
	"containers": [
		{
			"image": "./Dockerfile",
			"instance_type": {
				"vcpu": 1,
				"memory_mib": 1024,
				"disk_mb": 4000,
			},
		},
	],
}
[[containers]]
image = "./Dockerfile"

  [containers.instance_type]
  vcpu = 1
  memory_mib = 1_024
  disk_mb = 4_000

SSH

Wrangler 経由で Container インスタンスへ SSH 接続するための設定です。SSH で Containers へ接続する手順は SSH を参照してください。

次のオプションが使えます。

  • enabled boolean optional
    • Wrangler 経由の SSH を有効にするかどうか。デフォルトは true です。SSH アクセスを無効にするには false にします。
  • port number optional
    • SSH サービスが使うポートです。デフォルトは 22 です。

Authorized keys

authorized key は、Container へ SSH するために使える公開鍵です。

キーのプロパティは次のとおりです。

  • name string required
    • キーの表示名です。
  • public_key string required
    • 公開鍵そのものです。
    • 現在サポートされるキータイプは ssh-ed25519 のみです。

バンドリング

Wrangler は 2 つのモードで動作できます。デフォルトのバンドリングモードと --no-bundle モードです。 バンドリングモードでは、Wrangler はコードのすべてのインポートを走査し、単一の JavaScript「エントリポイント」ファイルを生成します。 インポートされたソースコードは、このエントリポイントファイルへ「インライン / バンドル」されます。

Worker へ追加モジュールを含めることもできます。これらはエントリポイントと一緒にアップロードされます。 Worker に含める追加モジュールは rules キーで指定し、Worker が呼び出されたときにインポートできるようにします。 rules キーは次のオブジェクトの配列になります。

  • type string required
    • モジュールの型です。次のいずれかである必要があります: ESModule、CommonJS、CompiledWasm、Text、Data。
  • globs string[] required
    • glob ルールの配列です（例: ["**/*.md"]）。glob ↗ を参照してください。
  • fallthrough boolean optional
    • ルールで true にすると、同じ Type に対して複数のルールを持てます。

例:

{
	"rules": [
		{
			"type": "Text",
			"globs": ["**/*.md"],
			"fallthrough": true,
		},
	],
}
[[rules]]
type = "Text"
globs = [ "**/*.md" ]
fallthrough = true

Worker 内でのモジュールのインポート

Worker 内では、次のようにこれらのモジュールをインポートして参照できます。

index.jsjs
import markdown from "./example.md";

export default {
	async fetch() {
		return new Response(markdown);
	},
};

追加モジュールを探す

通常、Wrangler は上記の例のように、ソースコードで静的にインポートされた追加モジュールだけを含めます。 設定ファイルで find_additional_modules を true にすると、Wrangler は base_dir 以下のファイルツリーを走査します。 rules に一致するファイルも、デプロイする Worker にバンドルされない外部モジュールとして含まれます。 base_dir のデフォルトは、main エントリポイントを含むディレクトリです。

詳細と例は https://developers.cloudflare.com/workers/wrangler/bundling/ ↗ を参照してください。

Python Workers

デフォルトでは、Python Workers は Worker のルート（Wrangler 設定ファイルと同じ階層）にある python_modules 内のファイルとフォルダーをバンドルします。 このディレクトリ内のファイルはベンダーしたパッケージを表し、pywrangler ツールがパッケージをコピーする場所です。場合によっては、このフォルダー内のファイルが大きすぎることがあります。Worker がそれらを必要としないなら、バンドルサイズが無駄に増えるだけです。

これを直すには、特定のファイルを除外できます。そのためには python_modules.exclude オプションを使います。例:

{
	"python_modules": {
		"exclude": ["**/*.pyc", "**/__pycache__"],
	},
}
[python_modules]
exclude = [ "**/*.pyc", "**/__pycache__" ]

これにより、python_modules 内の任意のサブディレクトリにある .pyc ファイルと __pycache__ ディレクトリが除外されます。

デフォルトでは python_modules.exclude は ["**/*.pyc"] です。別の値に設定するときは、これを含めてください。

ローカル開発設定

ローカルプロトコルやポートなど、ローカル開発のさまざまな側面を設定できます。

  • ip string optional
  • ローカル開発サーバーが待ち受ける IP アドレスです。デフォルトは localhost です。
  • port number optional
  • ローカル開発サーバーが待ち受けるポートです。デフォルトは 8787 です。
  • local_protocol string optional
    • ローカル開発サーバーがリクエストを待ち受けるプロトコルです。デフォルトは http です。
  • upstream_protocol string optional
    • ローカル開発サーバーがリクエストを転送するプロトコルです。デフォルトは https です。
  • host string optional
    • リクエストの転送先ホストです。デフォルトは Worker の最初の route のホストです。
  • enable_containers boolean optional
    • コンテナが設定されている場合、ローカル開発セッション中にコンテナを有効にするかどうかを決めます。デフォルトは true です。false にすると、コンテナとやり取りするコードを呼び出さない限り、Docker などのコンテナツールなしでアプリケーションのほかの部分を開発できます。
  • container_engine string optional
    • Containers のローカル開発に使います。Wrangler は、コンテナエンジンと通信するための正しいソケットを自動検出します。うまくいかない場合（通常は Container への接続時に internal error として現れます）、このオプションでソケットパスを設定できます。環境変数 DOCKER_HOST でも設定できます。
  • generate_types boolean optional
    • Worker 設定から型を生成します。デフォルトは false です。
{
	"dev": {
		"ip": "192.168.1.1",
		"port": 8080,
		"local_protocol": "http",
	},
}
[dev]
ip = "192.168.1.1"
port = 8_080
local_protocol = "http"

Secrets

Secrets は、Worker に 暗号化されたテキスト値を付ける バインディングの一種です。

secrets 設定プロパティ

secrets 設定プロパティを使うと、Worker が必要とするシークレット名を Wrangler 設定ファイルで宣言できます。必須シークレットはローカル開発とデプロイ時に検証され、型生成の信頼できる情報源として使われます。

{
	"secrets": {
		"required": ["API_KEY", "DB_PASSWORD"],
	},
}
[secrets]
required = [ "API_KEY", "DB_PASSWORD" ]

型生成

いずれかの設定レベルで secrets が定義されている場合、wrangler types は secrets.required に列挙された名前から型付きバインディングを生成し、.dev.vars や .env ファイルからシークレット名を推論しなくなります。これにより、それらのファイルがない環境でも型生成を実行できます。

環境ごとのシークレットにも対応します。名前付き環境ごとに独自のインターフェイスが作られ、集約された Env 型では一部の環境にしかないシークレットが任意になります。

デプロイ

secrets が定義されている場合、wrangler deploy と wrangler versions upload は、操作が成功する前に secrets.required のすべてのシークレットが Worker に設定されていることを検証します。必須シークレットが欠けている場合、コマンドは失敗し、設定が必要なシークレットを列挙したエラーを出します。

ローカル開発

ローカル開発で使うシークレットは、Wrangler 設定ファイルと同じディレクトリの .dev.vars または .env に置きます。

これらのファイルは dotenv ↗ の構文で記述します。例:

.dev.vars / .envbash
SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Cloudflare 環境ごとに異なるシークレットを設定するには、.dev.vars.<environment-name> または .env.<environment-name> という名前のファイルを作成します。

ローカル開発で Cloudflare 環境を選ぶと、対応する環境固有のファイルが、汎用の .dev.vars（または .env）より先に読み込まれます。

  • .dev.vars.<environment-name> を使う場合、すべてのシークレットを環境ごとに定義する必要があります。.dev.vars.<environment-name> が存在すると、そのファイルだけが読み込まれ、.dev.vars は読み込まれません。
  • 一方、一致する .env ファイルはすべて読み込まれ、値がマージされます。各変数には、もっとも具体的なファイルの値が使われます。優先順位は次のとおりです。
    • .env.<environment-name>.local（もっとも具体的）
    • .env.local
    • .env.<environment-name>
    • .env（もっとも汎用）

モジュールエイリアス

特定のパッケージをインポートするすべての呼び出しを、好きなモジュールへ置き換えるよう Wrangler を設定できます。alias フィールドで設定します。

{
	"alias": {
		"foo": "./replacement-module-filepath",
	},
}
[alias]
foo = "./replacement-module-filepath"
replacement-module-filepath.jsjs
export const bar = "baz";

上記の設定では、モジュール foo への import または require() の呼び出しは、置き換えモジュールを指すようエイリアスされます。

import { bar } from "foo";

console.log(bar); // returns "baz"

バンドリングの問題

Wrangler が Worker をバンドルするとき、依存関係の解決に失敗することがあります。そのような依存関係にエイリアスを設定すると、簡単に直せます。

ただし先に、そのパッケージがプロジェクトに正しくインストールされていることを確認します。package.json の直接依存関係として、または推移的依存関係としてです。

エイリアスが依存関係の問題の正しい解決策である場合、いくつかの選択肢があります。

  • 代替実装 — モジュールのロジックを Worker 互換の方法で実装し、機能が失われないようにします。
  • no-op モジュール — モジュールのロジックが未使用または無関係なら、エイリアスを空ファイルへ向けます。バンドリング問題を直しつつ、モジュールを no-op にします。
  • ランタイムエラー — モジュールのロジックが未使用で、Worker がそれを使おうとすべきでない場合（セキュリティ脆弱性など）、エイリアスをトップレベルの throw 文だけのファイルへ向けます。バンドリング問題を直しつつ、モジュールが実際に使われないようにします。

例: NPM からの依存関係のエイリアス

モジュールエイリアスを使い、Workers では動かない NPM パッケージの実装を提供できます。その NPM パッケージに間接的に依存している場合、つまり Worker の依存関係の依存関係であっても同様です。

たとえば、一部の NPM パッケージは node-fetch ↗ に依存します。これは、fetch() API のポリフィルを、Node.js に組み込まれる前に提供していたパッケージです。

Workers では node-fetch は不要です。fetch() API は Workers ランタイムが提供するからです。また node-fetch は Workers では動きません。現在未対応の http / https モジュールの Node.js API に依存するためです。

node-fetch のすべてのインポートを、Workers ランタイムに組み込みの fetch() API へ直接向けるようエイリアスできます。

{
	"alias": {
		"node-fetch": "./fetch-polyfill",
	},
}
[alias]
node-fetch = "./fetch-polyfill"
./fetch-polyfilljs
export default fetch;

例: Node.js API のエイリアス

モジュールエイリアスを使い、Workers ランタイムにまだない Node.js API の独自ポリフィル実装を提供できます。

たとえば、依存している NPM パッケージが fs.readFile ↗ を呼ぶとします。Worker の Wrangler 設定ファイルに次を追加して、fs モジュールをエイリアスできます。

{
	"alias": {
		"fs": "./fs-polyfill",
	},
}
[alias]
fs = "./fs-polyfill"
./fs-polyfilljs
export function readFile() {
	// ...
}

多くの場合、これで依存関係を動かすのに十分な API だけを提供できます。Cloudflare Workers の Node.js API サポートの詳細は、Cloudflare Workers Node.js API のドキュメント を参照してください。

ソースマップ

ソースマップ は、コンパイルおよび minify されたコードを、書いた元のコードへ戻します。ソースマップは、JavaScript ランタイムが返すスタックトレースと組み合わされ、スタックトレースを表示します。

  • upload_source_maps boolean
    • upload_source_maps が true のとき、Wrangler は wrangler deploy または wrangler versions deploy の実行時にソースマップファイルを自動生成してアップロードします。

例:

{
	"upload_source_maps": true,
}
upload_source_maps = true

Workers Sites

Workers Sites を使うと、静的ウェブサイト、または Vue や React などのフレームワークを使った動的ウェブサイトを Workers 上でホストできます。

  • bucket string required
    • 静的アセットを含むディレクトリです。Wrangler 設定ファイルからの相対パスである必要があります。
  • include string[] optional
    • バケット位置のファイル名またはディレクトリ名に一致する、.gitignore 形式のパターンの排他リストです。一致した項目だけがアップロードされます。
  • exclude string[] optional
    • バケット内のファイルまたはディレクトリに一致し、アップロードから除外すべき .gitignore 形式のパターンのリストです。

例:

{
	"site": {
		"bucket": "./public",
		"include": ["upload_dir"],
		"exclude": ["ignore_dir"],
	},
}
[site]
bucket = "./public"
include = [ "upload_dir" ]
exclude = [ "ignore_dir" ]

プロキシサポート

企業ネットワークにはしばしばプロキシがあり、接続の問題を起こすことがあります。適切なプロキシ情報で Wrangler を設定するには、次の環境変数を追加 します。

  • https_proxy
  • HTTPS_PROXY
  • http_proxy
  • HTTP_PROXY

macOS で設定するには、Wrangler コマンドの前に HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT> を付けます。

例:

$ HTTP_PROXY=http://localhost:8080 wrangler dev

IT チームがコンピューターのプロキシ設定を構成している場合、このリストで最初の空でない環境変数が、Wrangler の送信リクエストに使われることに注意してください。

たとえば https_proxy と http_proxy の両方が設定されている場合、Wrangler は送信リクエストに https_proxy だけを使います。

信頼できる情報源

Worker 設定の信頼できる情報源として Wrangler 設定ファイルを扱い、Wrangler を使っている場合は Cloudflare ダッシュボードから Worker を変更しないことを推奨します。

Cloudflare ダッシュボードから Worker を変更する必要がある場合、ダッシュボードは Wrangler 設定ファイルへコピーするための TOML スニペットを生成します。これにより、Wrangler 設定ファイルを常に最新に保てます。

Cloudflare ダッシュボードで環境変数を変更すると、次回のデプロイで Wrangler がそれらを上書きします。この動作を無効にするには、Wrangler 設定ファイルに keep_vars = true を追加します。

ダッシュボードでルートを変更すると、次回のデプロイで Wrangler は Wrangler 設定ファイルに設定したルートで上書きします。ルートを Cloudflare ダッシュボードだけで管理するには、Wrangler 設定ファイルから route と routes キーを削除します。次に Wrangler 設定ファイルへ workers_dev = false を追加します。詳細は Deprecations を参照してください。

Wrangler は、wrangler secret delete <key> を実行しない限り、シークレット（暗号化された環境変数）を削除しません。

生成された Wrangler 設定

一部のフレームワークツールやカスタムの事前ビルド処理は、Worker コードのデプロイに使う変更済み Wrangler 設定を生成します。 この場合、ツールは特別な .wrangler/deploy/config.json ファイルも作り、Wrangler にユーザーの元の設定ではなく生成された設定を使うようリダイレクトします。

Wrangler がこの生成された設定を使うのは、次のデプロイおよび開発関連コマンドだけです。

  • wrangler deploy
  • wrangler dev
  • wrangler versions upload
  • wrangler versions deploy
  • wrangler pages deploy
  • wrangler pages functions build

これらのコマンドを実行するとき、Wrangler は現在の作業ディレクトリからディレクトリツリーを上へ探し、パス .wrangler/deploy/config.json のファイルを探します。 このファイルには、次の形式の単一 JSON オブジェクトだけを含める必要があります。

{ "configPath": "../../path/to/wrangler.jsonc" }

この config.json ファイルがある場合、Wrangler は configPath（.wrangler/deploy/config.json ファイルからの相対）をたどり、現在のコマンドで読み込んで使う生成済み Wrangler 設定ファイルを見つけます。 Wrangler は、設定がユーザーの設定ファイルとは別のファイルへリダイレクトされたことを示すメッセージを表示します。

生成された設定ファイルには environments を含めないでください。 そのようなファイルは必要なときにビルドステップの一部として作られるべきで、すでに特定の環境を対象にしているためです。これらのビルドツールは、環境ごとに別々のデプロイ設定ファイルを生成する必要があります。

カスタムビルドツールの例

リダイレクトされた設定の一般的な例は、カスタムビルドツールまたはフレームワークが、ユーザーの設定をデプロイ用に変更し、dist ディレクトリへ新しい設定を生成する場合です。

  • まず、ユーザーは Cloudflare Workers リソースを使うコードを書き、次のようなユーザーの Wrangler 設定ファイルで設定します。

    {
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"main": "src/index.ts",
	"vars": {
		"MY_VARIABLE": "production variable",
	},
	"env": {
		"staging": {
			"vars": {
				"MY_VARIABLE": "staging variable",
			},
		},
	},
}
    "$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.ts"

[vars]
MY_VARIABLE = "production variable"

[env.staging.vars]
MY_VARIABLE = "staging variable"

    この設定は main をユーザーのコードエントリポイントへ向け、2 つの異なる環境で MY_VARIABLE 変数を定義します。

  • 次に、ユーザーは特定の環境（例: staging）向けのカスタムビルドを実行します。これにより、ソースコードのエントリポイントと環境固有の設定を見つけるために、ユーザーの Wrangler 設定ファイルが読み込まれます。

    > my-tool build --env=staging

  • my-tool は、コンパイル済みコードと、指定した環境の設定だけを含む新しい生成済みデプロイ設定ファイルの両方を含む dist ディレクトリを生成します。 また、Wrangler を新しい生成済みデプロイ設定ファイルへリダイレクトする .wrangler/deploy/config.json ファイルも作ります。

    • dist/
      • index.js
      • wrangler.jsonc
    • .wrangler/
      • deploy/
        • config.json

生成された dist/wrangler.jsonc には次のような内容が入ります。

{
	"name": "my-worker",
	"main": "./index.js",
	"vars": {
		"MY_VARIABLE": "staging variable"
	}
}

これで main プロパティは生成されたコードのエントリポイントを指し、環境は定義されず、 MY_VARIABLE 変数は staging 環境の値に解決されます。

そして .wrangler/deploy/config.json には、生成された設定ファイルへのパスが含まれます。

{
	"configPath": "../../dist/wrangler.jsonc"
}

役に立ちましたか？