設定

注意

This page is for Wrangler v1, which has now been deprecated. Access documentation for the current version of Wrangler by visiting the Wrangler homepage. Refer to the Migration guide for instructions on how to migrate to the latest version.

背景

プロジェクトを公開する前に、いくつかの設定が必要です。設定は、プロジェクトディレクトリのルートにある wrangler.toml ファイルに保存されたキーと値の変更を通じて行います。このファイルを手動で編集して、公開する前にキーと値を変更する必要があります。

---

環境

トップレベルの設定は、wrangler.toml ファイルの最上部で指定した値のコレクションです。これらの値は、環境で別途定義されていない限り、すべての環境に継承されます。

wrangler.toml ファイルにおけるトップレベルの設定のレイアウトは以下の通りです：

name = "your-worker"
type = "javascript"
account_id = "your-account-id"

# このフィールドは、Worker
# が *.workers.dev ドメインにデプロイされることを指定します
workers_dev = true

# -- または --

# これらのフィールドは、Worker
# がカスタムドメインにデプロイされることを指定します
zone_id = "your-zone-id"
routes = ["example.com/*"]

環境設定（オプション）：wrangler.toml ファイルの [env.name] の下に指定した設定値です。

環境を使用すると、同じプロジェクトを複数の場所に異なる名前でデプロイできます。これらの環境は、ライブ Worker をデプロイする際に使用される commands の --env または -e フラグと共に利用されます：

• build
• dev
• preview
• publish
• secret

一部の環境プロパティは、トップレベルの設定から 継承 されることがありますが、環境で新しい値が設定されると、それは常にトップレベルの値を上書きします。

[env.name] 設定の例は以下の通りです：

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]
# "helloworld" 環境のための設定キーを追加しています。
# これらの新しい値は、トップレベルの設定を上書きします。
name = "your-worker-helloworld"
account_id = "your-other-account-id"

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

kv_namespaces = [
  # 各環境のために kv 名前空間のバインディングを再宣言します
  # 注：この場合、新しい `account_id` 値のために新しい ID を渡しています。
  { binding = "FOO", id = "888...", preview_id = "999..." }
]

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

---

キー

wrangler.toml ファイルには、3種類のキーがあります：

• トップレベルのみのキーは、wrangler.toml ファイルのトップレベルでのみ設定する必要があります。同じプロジェクトの複数の環境は、このキーの値を共有しなければなりません。

• 継承されたキーは、トップレベルおよび/または環境で設定できます。キーがトップレベルでのみ定義されている場合、環境はトップレベルのキーの値を使用します。キーが環境で定義されている場合、環境の値はトップレベルの値を上書きします。

• 非継承キーは、各環境ごとに個別に定義する必要があります。

• name 継承必須

  • Worker スクリプトの名前です。継承される場合、環境名がトップレベルに追加されます。

• type トップレベル必須

  • wrangler build がプロジェクトをどのようにビルドするかを指定します。3つのオプションがあります：javascript、webpack、および rust。javascript は [build] セクションで指定されたビルドコマンドをチェックし、webpack は webpack v4 を使用してプロジェクトをビルドし、rust はプロジェクト内の Rust を WebAssembly にコンパイルします。

ノート

Cloudflare は rust および webpack プロジェクトタイプを引き続きサポートしますが、javascript プロジェクトタイプの使用を推奨し、カスタム build セクションを指定することを推奨します。

• 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/*"。route または routes キーは、*.workers.dev サブドメインを使用していない場合にのみ必要です。

• routes 非継承オプション

  • Worker を使用したいルートのリストです。これらは route と全く同じルールに従いますが、リストを指定できます。
    routes = ["http://example.com/hello", "http://example.com/goodbye"]。route または routes キーは、*.workers.dev サブドメインを使用していない場合にのみ必要です。

• webpack_config 継承オプション

  • Worker のためのカスタム webpack 設定ファイルへのパスです。このフィールドを指定しないと、Wrangler はデフォルトの設定を使用します。詳細については、Wrangler webpack ページを参照してください。

• vars 非継承オプション

  • Worker スクリプト内で直接アクセスできるテキスト変数を含むオブジェクトです。

• kv_namespaces 非継承オプション

  • Worker 内部からアクセスしたい Workers KV 名前空間を指定します。

• site 継承オプション

  • Worker からアップロードして提供するローカルフォルダを決定します。

• dev 非継承オプション

  • ローカルサーバーを構成する wrangler dev の引数です。

• triggers 継承オプション

  • Worker をスケジュールで実行するための cron トリガーを構成します。

• usage_model 継承オプション

  • Worker の Usage Model を指定します。2つのオプションがあります - bundled と unbound。新しく作成された Worker の場合、Usage Model が省略されると、アカウントに設定されたデフォルトの Usage Model ↗ に設定されます。既存の Worker の場合、Usage Model が省略されると、その Worker のダッシュボードで設定された Usage Model に設定されます。

• build トップレベルオプション

  • Worker をビルドする際に Wrangler によって実行されるカスタムビルドステップを構成します。詳細については、カスタムビルドのドキュメントを参照してください。

vars

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

使用法：

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

テーブルのキーは、関連する値を含むグローバル変数として Worker に利用可能です。

// Worker コード:
console.log(FOO);
//=> "some value"

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

また、インラインテーブル形式を使用して vars を定義することもできます。このスタイルは、正当な TOML 設定と見なされるために改行を含めてはいけません：

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

ノート

秘密は wrangler secret コマンドを使用して処理する必要があります。

kv_namespaces

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

使用法：

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

また、次のように kv namespaces を定義することもできます：

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

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

環境変数や秘密と同様に、binding 名は Worker にグローバル変数として利用可能です。

// Worker スクリプト：

let value = await FOO.get("keyname");
//=> "keyname" の値を取得します
//=> FOO 変数から、これは
//=> "0f2ac...e279" KV 名前空間を指します

• binding 必須

  • コードが参照するグローバル変数の名前です。これは KV ランタイムインスタンス として提供されます。

• id 必須

  • binding が表すべき KV 名前空間の ID です。wrangler publish に必要です。

• preview_id 必須

  • binding が wrangler dev または wrangler preview 中に表すべき KV 名前空間の ID です。wrangler dev および wrangler preview に必要です。

ノート

KV 名前空間の作成は、Wrangler の KV コマンド を使用して処理できます。

kv_namespaces を 代替 TOML 構文 ↗を使用して定義することもできます。

site

wrangler generate --site または wrangler init --site で生成された Workers Site。

使用法：

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

• bucket 必須

  • 静的アセットを含むディレクトリです。wrangler.toml ファイルに対して相対パスでなければなりません。例：bucket = "./public"

• entry-point オプション

  • Worker スクリプトの場所です。デフォルトの場所は workers-site です。例：entry-point = "./workers-site"

• include オプション

  • bucket ロケーションからファイルまたはディレクトリ名に一致する .gitignore スタイルのパターンの排他的リストです。マッチしたアイテムのみがアップロードされます。例：include = ["upload_dir"]

• exclude オプション

  • アップロードから除外すべき bucket 内のファイルまたはディレクトリに一致する .gitignore スタイルのパターンのリストです。例：exclude = ["ignore_dir"]

site を 代替 TOML 構文 ↗を使用して定義することもできます。

ストレージ制限

非常に大きなページの場合、Workers Sites は理想的ではないかもしれません。ページまたはファイルごとに 25 MiB の制限があります。さらに、Wrangler はファイルのアセットマニフェストを作成し、これがスクリプトのサイズ制限にカウントされます。ファイルが多すぎると、Workers Sites を使用できない場合があります。

ファイル/ディレクトリの排他的な含め方

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

[site]
bucket = "./public"
entry-point = "workers-site"
include = ["included_dir"] # 配列でなければなりません。

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

ファイル/ディレクトリの除外

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

[site]
bucket = "./public"
entry-point = "workers-site"
exclude = ["excluded_dir"] # 配列でなければなりません。

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

Include > Exclude

include と exclude の両方のフィールドを提供した場合、include フィールドが使用され、exclude フィールドは無視されます。

デフォルトで無視されるエントリ

Wrangler は常に以下を無視します：

• node_modules
• 隠しファイルおよびディレクトリ
• シンボリックリンク

include/exclude パターンについての詳細

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

Sites Build のカスタマイズ

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 *"]

• crons オプション
  • Worker を実行するための各式が別々のスケジュールである cron 式 ↗ のセットです。

dev

wrangler dev の引数をここで設定できるため、繰り返し渡す必要がありません。

使用法：

[dev]
port = 9000
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のフォーマットに基づいて2つの構成があります：service-workerとmodules。

サービスワーカー

このセクションは、service-workerフォーマットのWorkerをカスタマイズするためのものです。これらのWorkerはaddEventListenerを使用し、以下のようになります：

addEventListener("fetch", (event) => {
  event.respondWith(new Response("私はサービスワーカーです！"));
});

使用法：

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

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

[build]

• command optional

  • Workerをビルドするために使用されるコマンドです。LinuxおよびmacOSでは、コマンドはshシェルで実行され、Windowsではcmdシェルで実行されます。&&および||シェル演算子を使用できます。

• cwd optional

  • コマンドの作業ディレクトリで、デフォルトはプロジェクトのルートディレクトリです。

• watch_dir optional

  • wrangler devを使用している間に変更を監視するディレクトリで、デフォルトはプロジェクトのルートディレクトリに対してsrcです。

[build.upload]

• format required

  • Workerスクリプトのフォーマットで、"service-worker"でなければなりません。

ノート

package.jsonのmainフィールドが公開したいWorkerを参照していることを確認してください。

モジュール

Workersは現在、ESモジュール構文をサポートしています。このフォーマットでは、サービスワーカーフォーマットとは異なり、ファイルやモジュールのコレクションをエクスポートできます。

モジュールWorkerは、addEventListener呼び出しの代わりにイベントハンドラをexportします。

モジュールは、エクスポートされたハンドラへの引数としてすべてのバインディング（KVネームスペース、環境変数、シークレット）を受け取ります。サービスワーカーフォーマットでは、これらのバインディングはグローバル変数として利用可能です。

ノート

サービスワーカーとモジュールワーカーのフォーマットの違いについては、fetch()ハンドラのドキュメントを参照してください。

アップロードされたモジュールは、他のアップロードされたESモジュールをimportすることができます。CommonJSフォーマットを使用している場合は、他のアップロードされたCommonJSモジュールをrequireできます。

import html from "./index.html";

export default {
  // * requestはサービスワーカーフォーマットの`event.request`と同じです
  // * waitUntil()およびpassThroughOnException()は、サービスワーカーフォーマットの`event`の代わりに`ctx`からアクセスできます
  // * envはKVネームスペース、Durable Objectネームスペース、Config変数、シークレットなどのバインディングが公開される場所であり、グローバルスコープに配置されるのではありません。
  async fetch(request, env, ctx) {
    const headers = { "Content-Type": "text/html;charset=UTF-8" };
    return new Response(html, { headers });
  },
};

Wranglerとモジュールを使用してWorkersプロジェクトを作成するには、[build]セクションを追加します：

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

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

[build]

• command optional

  • Workerをビルドするために使用されるコマンドです。LinuxおよびmacOSシステムでは、コマンドはshシェルで実行され、Windowsではcmdシェルで実行されます。&&および||シェル演算子を使用できます。

• cwd optional

  • コマンドの作業ディレクトリで、デフォルトはプロジェクトのルートディレクトリです。

• watch_dir optional

  • wrangler devを使用している間に変更を監視するディレクトリで、デフォルトはプロジェクトのルートディレクトリに対してsrcです。

[build.upload]

• format required

  • Workersスクリプトのフォーマットで、"modules"でなければなりません。

• dir optional

  • モジュールをアップロードするディレクトリで、デフォルトはプロジェクトのルートディレクトリに対してdistです。

• main required

  • dirからのメインモジュールの相対パスで、./プレフィックスを含みます。メインモジュールはESモジュールでなければなりません。ビルドスクリプトを持つプロジェクトでは、通常、JavaScriptバンドラーの出力を指します。

ノート

プロジェクトがCommonJSモジュールを使用して書かれている場合、ESモジュールシムを使用してハンドラとDurable Objectクラスを再エクスポートする必要があります。例として、modules-webpack-commonjs ↗テンプレートを参照してください。

• rules optional

  • どのモジュールをインポートし、どのタイプでインポートするかを定義する順序付きリストです。 テキスト、データ、コンパイル済みWasmモジュールを使用するためのルールを指定する必要があります。または、.jsファイルをCommonJSではなくESModuleとして扱いたい場合にも必要です。

デフォルト：

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

# これらのデフォルトルールを`wrangler.toml`に含める必要はありません。暗黙的です。
# デフォルトルールはリストの最後の2つのルールとして扱われます。

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

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

• type required

  • モジュールタイプ、受け入れ可能なオプションについては以下の表を参照してください。

• globs required

  • 指定されたファイルのモジュールタイプを決定するために使用されるUNIXスタイルのglobルール ↗です。グロブは、build.upload.dirからのモジュールの相対パスに対して./プレフィックスなしで一致します。ルールは、上から順に評価されます。

• fallthrough optional

  • このオプションは、trueに設定されている場合、このモジュールタイプのさらなるルールを考慮することを許可します。指定されていない場合やfalseに設定されている場合、このモジュールタイプのさらなるルールは無視されます。

---

例

これらのレベルがどのように適用されるかを示すために、複数の環境を使用したwrangler.tomlファイルを以下に示します：

# トップレベルの構成
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"
[build.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.staging]
name = "my-worker-staging"
route = "staging.example.com/*"
kv_namespaces = [
  { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279" },
  { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0" }
]

# 環境構成
[env.production]
workers_dev= true
kv_namespaces = [
  { binding = "FOO", id = "0d2ac74b498b48028cb68387c421e233" },
  { binding = "BAR", id = "0d8c101e168d03c65bddf4ba75150f33" }
]