設定 - Wrangler v1（非推奨） · Cloudflare Workers ドキュメント

背景

Worker を公開する前に、プロジェクトの設定が必要です。設定は、プロジェクトディレクトリのルートにある Wrangler ファイルのキーと値を変更して行います。公開する前に、このファイルを手動で編集してキーと値を更新します。

環境

トップレベルの設定は、Wrangler ファイルの先頭で指定する値の集まりです。環境側で上書きしない限り、これらの値はすべての環境に継承されます。

Wrangler ファイルのトップレベル設定の例は次のとおりです。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "your-worker",
	"type": "javascript",
	"account_id": "your-account-id",
	// This field specifies that the Worker
	// will be deployed to a *.workers.dev domain
	"workers_dev": true,
	// -- OR --
	// These fields specify that the Worker
	// will deploy to a custom domain
	"zone_id": "your-zone-id",
	"routes": [
		"example.com/*"
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "your-worker"
type = "javascript"
account_id = "your-account-id"
workers_dev = true
zone_id = "your-zone-id"
routes = [ "example.com/*" ]

環境設定（任意）: Wrangler ファイルの [env.name] の下で指定する設定値です。

環境を使うと、同じプロジェクトを複数の名前で複数の場所にデプロイできます。これらの環境は、稼働中の Workers をデプロイするコマンドの --env または -e フラグで使います。

build
dev
preview
publish
secret

一部の環境プロパティはトップレベル設定から継承できます。ただし、環境側で新しい値を設定した場合は、常にトップレベルの値を上書きします。

[env.name] 設定の例は次のとおりです。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"type": "javascript",
	"name": "your-worker",
	"account_id": "your-account-id",
	"vars": {
		"FOO": "default FOO value",
		"BAR": "default BAR value"
	},
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "1a...",
			"preview_id": "1b..."
		}
	],
	"env": {
		"helloworld": {
			// Now adding configuration keys for the "helloworld" environment.
			// These new values will override the top-level configuration.
			"name": "your-worker-helloworld",
			"account_id": "your-other-account-id",
			"vars": {
				"FOO": "env-helloworld FOO value",
				"BAR": "env-helloworld BAR value"
			},
			"kv_namespaces": [
				{
					// Redeclare kv namespace bindings for each environment
					// NOTE: In this case, passing new IDs because new `account_id` value.
					"binding": "FOO",
					"id": "888...",
					"preview_id": "999..."
				}
			]
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

[[kv_namespaces]]
binding = "FOO"
id = "1a..."
preview_id = "1b..."

[env.helloworld]
name = "your-worker-helloworld"
account_id = "your-other-account-id"

  [env.helloworld.vars]
  FOO = "env-helloworld FOO value"
  BAR = "env-helloworld BAR value"

  [[env.helloworld.kv_namespaces]]
  binding = "FOO"
  id = "888..."
  preview_id = "999..."

この例の Worker を helloworld 環境にデプロイするには、wrangler deploy --env helloworld を実行します。

キー

Wrangler ファイルのキーには、次の 3 種類があります。

トップレベルのみのキーは、Wrangler ファイルのトップレベルでのみ設定します。同じプロジェクトの複数の環境は、このキーの値を共有する必要があります。
継承されるキーは、トップレベル、環境、またはその両方で設定できます。トップレベルにだけ定義されている場合、環境はそのトップレベルの値を使います。環境側に定義されている場合、環境の値がトップレベルの値を上書きします。
継承されないキーは、環境ごとに個別に定義する必要があります。
name 継承される必須
- Worker スクリプトの名前です。継承する場合、環境名がトップレベルの名前に付加されます。
type トップレベル必須
- wrangler build がプロジェクトをどのようにビルドするかを指定します。選択肢は javascript、webpack、rust の 3 つです。javascript は [build] セクションで指定したビルドコマンドを確認し、webpack は webpack v4 でプロジェクトをビルドし、rust はプロジェクト内の Rust を WebAssembly にコンパイルします。

account_id 継承される必須
- ゾーンに紐づくアカウントの ID です。アカウントが複数ある場合があるので、zone_id を指定するときは、そのゾーンに紐づくアカウントの ID を使ってください。CF_ACCOUNT_ID 環境変数でも指定できます。
zone_id 継承される任意
- Worker を動かすゾーンまたはドメインの ID です。CF_ZONE_ID 環境変数でも指定できます。*.workers.dev サブドメインだけを使う場合、このキーは任意です。
workers_dev 継承される任意
- Worker を *.workers.dev ↗ サブドメインにデプロイするかどうかを示す真偽値です。省略するとデフォルトは false です。
route 継承されない任意
- Worker を動かすゾーン上のルートです。URL パターンで指定します。
  route = "http://example.com/*"。*.workers.dev ↗ サブドメインを使わない場合に限り、route または routes キーが必要です。
routes 継承されない任意
- Worker を使うルートのリストです。ルールは route と同じですが、複数指定できます。
  routes = ["http://example.com/hello", "http://example.com/goodbye"]。*.workers.dev サブドメインを使わない場合に限り、route または routes キーが必要です。
webpack_config 継承される任意
- Worker 用のカスタム webpack 設定ファイルへのパスです。カスタム webpack 設定を使う場合はこのフィールドを指定します。指定しないと、Wrangler がデフォルト設定を使います。詳細は Wrangler の webpack のページを参照してください。
vars 継承されない任意
- Worker スクリプトから直接アクセスできるテキスト変数を含むオブジェクトです。
kv_namespaces 継承されない任意
- Worker 内からアクセスする Workers KV 名前空間を指定します。
site 継承される任意
- Worker からアップロードして配信するローカルフォルダーを決めます。
dev 継承されない任意
- ローカルサーバーを設定する wrangler dev の引数です。
triggers 継承される任意
- スケジュールで Worker を実行する cron トリガーを設定します。
usage_model 継承される任意
- Worker の Usage Model を指定します。選択肢は bundled と unbound の 2 つです。新規作成した Worker で Usage Model を省略すると、アカウントのデフォルト Usage Model ↗ が設定されます。既存の Worker で省略すると、ダッシュボードでその Worker に設定されている Usage Model が使われます。
build トップレベル任意
- Worker のビルド時に Wrangler が実行するカスタムビルドステップを設定します。詳細はカスタムビルドのドキュメントを参照してください。

vars

vars キーは、Worker スクリプトに渡す環境変数のテーブルを定義します。値はすべてプレーンテキストです。

使い方:

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}

[vars]
FOO = "some value"
BAR = "some other string"

テーブルのキーは Worker からグローバル変数として使え、対応する値が入ります。

// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"

代わりに、インラインテーブル形式で vars を定義することもできます。有効な TOML 設定とみなすには、改行を含めないでください。

{
	"vars": {
		"FOO": "some value",
		"BAR": "some other string"
	}
}

[vars]
FOO = "some value"
BAR = "some other string"

kv_namespaces

kv_namespaces は、Worker の KV 名前空間バインディングのリストを定義します。

使い方:

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "0f2ac74b498b48028cb68387c421e279",
			"preview_id": "6a1ddb03f3ec250963f0a1e46820076f"
		},
		{
			"binding": "BAR",
			"id": "068c101e168d03c65bddf4ba75150fb0",
			"preview_id": "fb69528dbc7336525313f2e8c3b17db0"
		}
	]
}

[[kv_namespaces]]
binding = "FOO"
id = "0f2ac74b498b48028cb68387c421e279"
preview_id = "6a1ddb03f3ec250963f0a1e46820076f"

[[kv_namespaces]]
binding = "BAR"
id = "068c101e168d03c65bddf4ba75150fb0"
preview_id = "fb69528dbc7336525313f2e8c3b17db0"

代わりに、kv namespaces を次のように定義することもできます。

{
	"kv_namespaces": [
		{
			"binding": "FOO",
			"preview_id": "abc456",
			"id": "abc123"
		},
		{
			"binding": "BAR",
			"preview_id": "xyz456",
			"id": "xyz123"
		}
	]
}

[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"

環境変数やシークレットと同様に、binding 名は Worker からグローバル変数として使えます。

// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace

binding 必須
- コードが参照するグローバル変数の名前です。KV ランタイムインスタンスとして渡されます。
id 必須
- binding が表す KV 名前空間の ID です。wrangler publish で必須です。
preview_id 必須
- wrangler dev または wrangler preview のときに binding が表す KV 名前空間の ID です。wrangler dev と wrangler preview で必須です。

site

wrangler generate --site または wrangler init --site で生成した Workers Site です。

使い方:

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"

bucket 必須
- 静的アセットを含むディレクトリです。Wrangler ファイルからの相対パスである必要があります。例: bucket = "./public"
entry-point 任意
- Worker スクリプトの場所です。デフォルトは workers-site です。例: entry-point = "./workers-site"
include 任意
- bucket の場所にあるファイル名またはディレクトリ名に一致する、.gitignore 形式のパターンの排他リストです。一致した項目だけがアップロードされます。例: include = ["upload_dir"]
exclude 任意
- アップロードから除外する、bucket 内のファイルまたはディレクトリに一致する .gitignore 形式のパターンのリストです。例: exclude = ["ignore_dir"]

別の TOML 構文 ↗ で site を定義することもできます。

ストレージの上限

極端に大きいページでは、Workers Sites は向いていないことがあります。ページまたはファイルあたりの上限は 25 MiB です。さらに Wrangler はファイルのアセットマニフェストを作成し、これもスクリプトのサイズ上限に含まれます。ファイルが多すぎると、Workers Sites を使えない場合があります。

ファイル / ディレクトリだけを含める

bucket 内の特定のファイルまたはディレクトリだけを含めたい場合は、Wrangler ファイルの [site] セクションに include フィールドを追加します。

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"include": [ // must be an array.
			"included_dir"
		]
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"
include = [ "included_dir" ]

Wrangler は、include 配列のパターンに一致するファイルまたはディレクトリだけをアップロードします。

ファイル / ディレクトリを除外する

bucket 内のファイルまたはディレクトリを除外したい場合は、Wrangler ファイルの [site] セクションに exclude フィールドを追加します。

{
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site",
		"exclude": [ // must be an array.
			"excluded_dir"
		]
	}
}

[site]
bucket = "./public"
entry-point = "workers-site"
exclude = [ "excluded_dir" ]

アセットを Workers KV にアップロードするとき、Wrangler は exclude 配列のパターンに一致するファイルまたはディレクトリを無視します。

Include > Exclude

include と exclude の両方を指定した場合、include が使われ、exclude は無視されます。

デフォルトで無視される項目

Wrangler は常に次を無視します。

node_modules
隠しファイルと隠しディレクトリ
シンボリックリンク

include / exclude パターンの詳細

標準のマッチングパターンについては、gitignore のドキュメント ↗ を参照してください。

Sites のビルドをカスタマイズする

Workers Sites プロジェクトは、デフォルトで webpack を使います。独自の webpack 設定を持ち込める一方で、entry と context の設定に注意してください。

Workers Sites でも [build] セクションを使えます。ただし、ビルドステップが node_modules の依存関係を解決する必要があります。詳細はカスタムビルドセクションを参照してください。

triggers

スケジュールで Worker を呼び出す cron トリガーのセットです。

使い方:

{
	"triggers": {
		"crons": [
			"0 0 * JAN-JUN FRI",
			"0 0 LW JUL-DEC *"
		]
	}
}

[triggers]
crons = [ "0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *" ]

crons 任意
- cron 式 ↗ のセットです。各式が Worker を実行する別々のスケジュールになります。

dev

wrangler dev の引数をここに設定しておくと、毎回渡す必要がなくなります。

使い方:

{
	"dev": {
		"port": 9000,
		"local_protocol": "https"
	}
}

[dev]
port = 9_000
local_protocol = "https"

ip 任意
- ローカルの wrangler dev サーバーが待ち受ける IP アドレスです。デフォルトは 127.0.0.1 です。
port 任意
- ローカルの wrangler dev サーバーが待ち受けるポートです。デフォルトは 8787 です。
local_protocol 任意
- ローカルの wrangler dev サーバーがリクエストを受け取るプロトコルです。デフォルトは http です。
upstream_protocol 任意
- wrangler dev がリクエストを転送するプロトコルです。デフォルトは https です。

build

プロジェクト用のカスタムビルドコマンドです。Worker の形式に応じて、service-worker と modules の 2 通りの設定があります。

Service Workers

このセクションは、service-worker 形式の Workers をカスタマイズするためのものです。これらの Workers は addEventListener を使い、次のような形になります。

addEventListener("fetch", (event) => {
	event.respondWith(new Response("I'm a service Worker!"));
});

使い方:

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "service-worker"
		}
	}
}

[build]
command = "npm install && npm run build"

  [build.upload]
  format = "service-worker"

`[build]`

command 任意
- Worker のビルドに使うコマンドです。Linux と macOS では sh シェル、Windows では cmd シェルで実行されます。&& と || のシェル演算子を使えます。
cwd 任意
- コマンドの作業ディレクトリです。デフォルトはプロジェクトのルートディレクトリです。
watch_dir 任意
- wrangler dev 使用時に変更を監視するディレクトリです。デフォルトはプロジェクトルートからの相対パス src です。

`[build.upload]`

format 必須
- Worker スクリプトの形式です。"service-worker" である必要があります。

Modules

Workers は ES Modules 構文をサポートしています。この形式では、単一ファイルのアップロードが必要な Service Worker 形式と異なり、複数のファイルやモジュールをエクスポートできます。

Module Workers は addEventListener ではなく、イベントハンドラーを export します。

モジュールは、エクスポートしたハンドラーの引数として、すべてのバインディング（KV 名前空間、環境変数、シークレット）を受け取ります。Service Worker 形式では、これらのバインディングはグローバル変数として使えます。

アップロードしたモジュールは、ほかのアップロード済み ES Modules を import できます。CommonJS 形式の場合は、ほかのアップロード済み CommonJS モジュールを require できます。

import html from "./index.html";

export default {
	// * request is the same as `event.request` from the service worker format
	// * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
	// * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
	// are exposed, instead of them being placed in global scope.
	async fetch(request, env, ctx) {
		const headers = { "Content-Type": "text/html;charset=UTF-8" };
		return new Response(html, { headers });
	},
};

Wrangler と Modules を使って Workers プロジェクトを作るには、[build] セクションを追加します。

{
	"build": {
		"command": "npm install && npm run build",
		"upload": {
			"format": "modules",
			"main": "./worker.mjs"
		}
	}
}

[build]
command = "npm install && npm run build"

  [build.upload]
  format = "modules"
  main = "./worker.mjs"

`[build]`

command 任意
- Worker のビルドに使うコマンドです。Linux と macOS では sh シェル、Windows では cmd シェルで実行されます。&& と || のシェル演算子を使えます。
cwd 任意
- コマンドの作業ディレクトリです。デフォルトはプロジェクトのルートディレクトリです。
watch_dir 任意
- wrangler dev 使用時に変更を監視するディレクトリです。デフォルトはプロジェクトルートからの相対パス src です。

`[build.upload]`

format 必須
- Workers スクリプトの形式です。"modules" である必要があります。
dir 任意
- モジュールをアップロードするディレクトリです。デフォルトはプロジェクトルートからの相対パス dist です。
main 必須
- dir からのメインモジュールの相対パスです。./ プレフィックスを含めます。メインモジュールは ES モジュールである必要があります。ビルドスクリプトがあるプロジェクトでは、通常、JavaScript バンドラーの出力を指します。

rules 任意
- どのモジュールを、どの種類としてインポートするかを定義する、順序付きのルールリストです。 Text、Data、CompiledWasm モジュールを使う場合や、.js ファイルを CommonJS ではなく ESModule として扱いたい場合に、ルールを指定する必要があります。

デフォルト:

{
	// You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
	// The default rules are treated as the last two rules in the list.
	"build": {
		"upload": {
			"format": "modules",
			"main": "./worker.mjs",
			"rules": [
				{
					"type": "ESModule",
					"globs": [
						"**/*.mjs"
					]
				},
				{
					"type": "CommonJS",
					"globs": [
						"**/*.js",
						"**/*.cjs"
					]
				}
			]
		}
	}
}

[build.upload]
format = "modules"
main = "./worker.mjs"

  [[build.upload.rules]]
  type = "ESModule"
  globs = [ "**/*.mjs" ]

  [[build.upload.rules]]
  type = "CommonJS"
  globs = [ "**/*.js", "**/*.cjs" ]

type 必須
- モジュールの種類です。指定できる値は次の表を参照してください。
globs 必須
- dir 内のファイルにどのモジュール種類を使うかを決める、UNIX 形式の glob ルール ↗ です。glob は、モジュールの build.upload.dir からの相対パス（./ プレフィックスなし）に対して照合されます。ルールは上から順に評価されます。
fallthrough 任意
- true にすると、このモジュール種類の後続ルールも評価されます。未指定または false の場合、このモジュール種類の後続ルールは無視されます。

例

これらのレベルがどのように適用されるかを示すため、複数環境を使った Wrangler ファイルの例を示します。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	// top level configuration
	"type": "javascript",
	"name": "my-worker-dev",
	"account_id": "12345678901234567890",
	"zone_id": "09876543210987654321",
	"route": "dev.example.com/*",
	"usage_model": "unbound",
	"kv_namespaces": [
		{
			"binding": "FOO",
			"id": "b941aabb520e61dcaaeaa64b4d8f8358",
			"preview_id": "03c8c8dd3b032b0528f6547d0e1a83f3"
		},
		{
			"binding": "BAR",
			"id": "90e6f6abd5b4f981c748c532844461ae",
			"preview_id": "e5011a026c5032c09af62c55ecc3f438"
		}
	],
	"build": {
		"command": "webpack",
		"upload": {
			"format": "service-worker"
		}
	},
	"site": {
		"bucket": "./public",
		"entry-point": "workers-site"
	},
	"dev": {
		"ip": "0.0.0.0",
		"port": 9000,
		"local_protocol": "http",
		"upstream_protocol": "https"
	},
	"env": {
		// environment configuration
		"staging": {
			"name": "my-worker-staging",
			"route": "staging.example.com/*",
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0f2ac74b498b48028cb68387c421e279"
				},
				{
					"binding": "BAR",
					"id": "068c101e168d03c65bddf4ba75150fb0"
				}
			]
		},
		// environment configuration
		"production": {
			"workers_dev": true,
			"kv_namespaces": [
				{
					"binding": "FOO",
					"id": "0d2ac74b498b48028cb68387c421e233"
				},
				{
					"binding": "BAR",
					"id": "0d8c101e168d03c65bddf4ba75150f33"
				}
			]
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"

[[kv_namespaces]]
binding = "FOO"
id = "b941aabb520e61dcaaeaa64b4d8f8358"
preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3"

[[kv_namespaces]]
binding = "BAR"
id = "90e6f6abd5b4f981c748c532844461ae"
preview_id = "e5011a026c5032c09af62c55ecc3f438"

[build]
command = "webpack"

  [build.upload]
  format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9_000
local_protocol = "http"
upstream_protocol = "https"

[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"

  [[env.staging.kv_namespaces]]
  binding = "FOO"
  id = "0f2ac74b498b48028cb68387c421e279"

  [[env.staging.kv_namespaces]]
  binding = "BAR"
  id = "068c101e168d03c65bddf4ba75150fb0"

[env.production]
workers_dev = true

  [[env.production.kv_namespaces]]
  binding = "FOO"
  id = "0d2ac74b498b48028cb68387c421e233"

  [[env.production.kv_namespaces]]
  binding = "BAR"
  id = "0d8c101e168d03c65bddf4ba75150f33"