設定

注意

プロジェクトに既存の wrangler.toml ファイルが含まれている場合、以前にローカル開発に使用したものであることを確認し、Cloudflare ダッシュボードのプロジェクト設定と一致していることを確認してから、wrangler.toml を使用して Pages プロジェクトをデプロイすることを選択してください。手動で wrangler.toml ファイルを書く代わりに、Cloudflare は npx wrangler pages download config を使用して、現在のプロジェクト設定を wrangler.toml ファイルにダウンロードすることを推奨しています。

Pages Functions は、Cloudflare ダッシュボード ↗ または wrangler.toml を介して設定できます。wrangler.toml は、Workers と Pages Functions の開発およびデプロイメント設定をカスタマイズするために使用される設定ファイルです。

このページは、wrangler.toml を介して Pages プロジェクトを設定する方法のリファレンスとして機能します。

wrangler.toml を使用する場合、Pages プロジェクトの設定の真実のソースとして wrangler.toml を扱う必要があります。

wrangler.toml を介した設定はオープンベータ中です。

Cloudflare はあなたのフィードバックを歓迎します。バグを報告したり機能をリクエストするために、Cloudflare Developers Discord ↗ の #functions チャンネルに参加してください。

wrangler.toml を使用して Pages プロジェクトを設定することで、以下のことが可能になります：

• 設定ファイルをソース管理に保存する: 設定をリポジトリ内の他のコードと一緒に保持します。
• コードエディタを介して設定を編集する: インターフェース間を行き来する必要をなくします。
• 環境間で共有される設定を書く: ローカル開発、プレビュー、プロダクション用の設定を1つのファイルで定義します。
• より良いアクセス制御を確保する: プロジェクトリポジトリ内の設定ファイルを使用することで、Cloudflare ダッシュボードへのアクセスを与えずに、誰が変更を加えることができるかを制御できます。

例 wrangler.toml ファイル

name = "my-pages-app"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[[d1_databases]]
binding = "DB"
database_name = "northwind-demo"
database_id = "<DATABASE_ID>"

[vars]
API_KEY = "1234567asdf"

要件

V2 ビルドシステム

wrangler.toml を介した Pages Functions の設定には、V2 ビルドシステム 以上が必要です。V1 からの更新については、V2 ビルドシステムの移行手順を参照してください。

Wrangler

Pages プロジェクトの設定に wrangler.toml を使用するには、Wrangler バージョン 3.45.0 以上が必要です。Wrangler のバージョンを確認したり、Wrangler を更新またはインストールするには、Wrangler のインストール/更新を参照してください。

ダッシュボード設定からの移行

現在 wrangler.toml ファイルを持たない Pages プロジェクトの移行手順は、既存の wrangler.toml ファイルを持つ Pages プロジェクトの手順とは異なります。プロダクションでのエラーを避けるために、状況に応じた手順を注意深くお読みください。

既存の wrangler.toml ファイルを持つプロジェクト

プレビューおよびプロダクションの設定を定義するために wrangler.toml を使用する前に、ローカル開発で Pages プロジェクトにどの bindings が利用可能であるべきかを定義するために wrangler.toml を使用することが可能でした。

ローカル開発に wrangler.toml を使用している場合、すでに次のようなファイルが Pages プロジェクトに存在するかもしれません：

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

既存の wrangler.toml ファイルを Pages プロジェクトの設定に使用したい場合は、次のことを行う必要があります：

1. 適切な値の pages_build_output_dir キーを追加します。ビルド出力ディレクトリ（例えば、pages_build_output_dir = "./dist"）を指定します。
2. デプロイする前に、既存の wrangler.toml 設定が希望するプロジェクト設定と一致していることを確認するために注意深くレビューします。

wrangler.toml に pages_build_output_dir キーを追加して Pages プロジェクトをデプロイすると、Pages はローカル用に定義された設定を使用しますが、それは非常に可能性が高くプロダクションではありません。wrangler.toml がプロダクション用に準備が整うまでデプロイしないでください。

設定の上書き

wrangler pages download config を実行すると、Cloudflare ダッシュボードの設定に基づいて生成された wrangler.toml ファイルで既存の wrangler.toml ファイルが上書きされます。このコマンドは、ローカル開発に使用していた以前の wrangler.toml ファイルを破棄して、Cloudflare ダッシュボードから引き出した設定でやり直したい場合のみ実行してください。

pages_build_output_dir キーを追加せずに wrangler.toml ファイルをローカル開発に引き続き使用することができます。pages_build_output_dir キーを追加せずに wrangler pages deploy を実行すると、フィールドが欠落しているという警告メッセージが表示され、そのファイルはローカル開発専用として使用され続けることになります。

既存の wrangler.toml ファイルを持たないプロジェクト

Cloudflare ダッシュボードを介して設定された既存の Pages プロジェクトがあり、プロジェクトに既存の wrangler.toml ファイルがない場合は、Pages プロジェクトディレクトリで wrangler pages download config コマンドを実行します。このコマンドは、既存の Cloudflare ダッシュボード設定をダウンロードし、Pages プロジェクトディレクトリに有効な wrangler.toml ファイルを生成します。

npm

npx wrangler pages download config <PROJECT_NAME>

yarn

yarn wrangler pages download config <PROJECT_NAME>

pnpm

pnpm wrangler pages download config <PROJECT_NAME>

生成された wrangler.toml ファイルを確認してください。Pages プロジェクトの設定に wrangler.toml を使用し始めるには、Git 統合 または 直接アップロードを介して新しいデプロイメントを作成します。

“Latest” に設定された互換性日付の取り扱い

Cloudflare ダッシュボードでは、プレビューのデプロイメントの互換性日付を “Latest” に設定できます。これにより、明示的に設定する必要なく、プロジェクトが常に最新の互換性日付を使用することが保証されます。

wrangler pages download コマンドを使用して “Latest” で設定されたプロジェクトから wrangler.toml をダウンロードすると、ダウンロード時点で利用可能な最新の互換性日付が wrangler.toml に設定されます。Wrangler はダッシュボードのように “Latest” 機能をサポートしていません。wrangler.toml を使用する場合、互換性日付は明示的に設定する必要があります。

互換性日付が何であるか、どのように機能するかについての詳細は、このガイドを参照してください。

Pages Functions と Workers の wrangler.toml 使用の違い

Workers を使用したことがある場合、wrangler.toml にすでに慣れているかもしれません。Pages Functions プロジェクトで wrangler.toml を使用する際に注意すべきいくつかの重要な違いがあります：

• 設定フィールドは、Pages Functions の wrangler.toml ファイルと Workers の同等のものの間で 正確に一致しません。例えば、Workers 特有の設定キー main は、Pages Function の wrangler.toml には適用されません。
• Pages の wrangler.toml には、Pages プロジェクト専用の新しいキー pages_build_output_dir が導入されています。
• このファイルにおける 環境 の概念と設定の継承は、Workers とは 異なります。
• このファイルは使用されると、真実のソース となり、使用を開始するとダッシュボードで同じフィールドを編集することは できません。

環境の設定

wrangler.toml を使用すると、ローカル環境、プレビューのデプロイメント、プロダクション全体で設定を迅速に設定できます。

ローカル開発

wrangler.toml は wrangler pages dev を使用する際にローカルで機能します。これにより、Cloudflare ダッシュボードにログインする必要なく、設定変更を迅速にテストできます。以下の設定ファイルの例を参照してください：

name = "my-pages-app"
pages_build_output_dir = "./dist"
compatibility_date = "2023-10-12"
compatibility_flags = ["nodejs_compat"]

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

この wrangler.toml 設定ファイルは、nodejs_compat 互換性フラグと KV 名前空間バインディングを Pages プロジェクトに追加します。この wrangler.toml 設定ファイルを持つ Pages プロジェクトディレクトリで wrangler pages dev を実行すると、nodejs_compat 互換性フラグがローカルで適用され、Pages Function コード内の context.env.KV で KV バインディングが公開されます。

ノート

設定キーの完全なリストについては、継承可能なキー と 非継承可能なキー を参照してください。

プロダクションおよびプレビューのデプロイメント

プロジェクトをデプロイする準備が整ったら、wrangler.toml ファイルを含む新しいデプロイメントを作成することで、プロダクションおよびプレビューのデプロイメントの設定を行うことができます。

ノート

以下のコマンドを使用する場合、git を使用している場合は、プロダクションブランチとして設定したブランチと、プレビューブランチ設定を覚えておくことが重要です。

上記の例をプロダクションの設定として使用するには、次のコマンドを使用して新しいプロダクションデプロイメントを作成します：

npx wrangler pages deploy

または、より具体的には：

npx wrangler pages deploy --branch <PRODUCTION BRANCH>

プレビューのデプロイメントの設定をデプロイするには、プレビューのデプロイメントで動作するように設定したブランチにいる間に、上記と同じコマンドを実行できます。これにより、特定のブランチからのデプロイメントだけでなく、すべてのプレビューのデプロイメントの設定が行われます。Pages は現在、ブランチベースの設定をサポートしていません。

ノート

--branch フラグは wrangler pages deploy ではオプションです。git 統合を使用する場合、Wrangler は現在いるリポジトリからブランチを推測し、コマンドに暗黙的に追加します。

環境固有のオーバーライド

ローカル、プレビューのデプロイメント、プロダクションで異なる設定を使用したい場合があります。[env.production] または [env.preview] を使用して、プロダクションおよびプレビューのデプロイメントの設定をオーバーライドすることが可能です。

ノート

Workers Environments とは異なり、production と preview は [env.<ENVIRONMENT>] を介して利用可能な唯一の2つのオプションです。

プレビューのデプロイメント設定をオーバーライドする方法の例として、以下の wrangler.toml 設定ファイルを参照してください：

name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

このファイルを wrangler pages deploy を介してデプロイすると、name、pages_build_output_dir、kv_namespaces、および vars はローカルおよびプロダクションに設定が適用され、env.preview はプレビューのデプロイメントのために kv_namespaces と vars をオーバーライドします。

ローカルとプレビューに設定値を適用し、プロダクションをオーバーライドしたい場合、ファイルは次のようになります：

name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "8901234bfgd"

プレビューとプロダクションの両方を明示的にオーバーライドすることもできます：

name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "6567875fvgt"

継承可能なキー

継承可能なキーは、トップレベルで設定可能で、環境固有の設定によって継承（またはオーバーライド）されることができます。

• name string 必須

  • Pages プロジェクトの名前。英数字とダッシュのみ。

• pages_build_output_dir string 必須

  • プロジェクトのビルド出力フォルダへのパス。例えば：./dist。

• compatibility_date string 必須

  • yyyy-mm-dd 形式の日付で、使用される Workers ランタイムのバージョンを決定するために使用されます。互換性日付を参照してください。

• compatibility_flags string[] オプション

  • Workers ランタイムの今後の機能を有効にするフラグのリストで、通常は compatibility_date と一緒に使用されます。互換性日付を参照してください。

• send_metrics boolean オプション

• WranglerがこのプロジェクトのためにCloudflareに使用状況メトリクスを送信すべきかどうか。

• limits 限界（オプション）

  • 実行時に課せられる制限を設定します。詳細はLimitsを参照してください。

• placement 配置（オプション）

  • Pages Functionsがラウンドトリップ時間を最小限に抑えるためにどのように配置されるべきかを指定します。詳細はSmart Placementを参照してください。

• upload_source_maps ブール値

  • upload_source_mapsがtrueに設定されている場合、WranglerはあなたのPagesプロジェクトのサーバーサイドソースマップをアップロードし、ログに修正されたスタックトレースを提供します。

継承不可のキー

継承不可のキーはトップレベルで設定可能ですが、環境ごとに1つの継承不可のキーがオーバーライドされると（例えば、[[env.production.kv_namespaces]]）、すべての継承不可のキーも環境設定で指定し、オーバーライドする必要があります。

例えば、この設定は機能しません：

name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[env.production.vars]
API_KEY = "8901234bfgd"

[[env.production.vars]]は[vars]をオーバーライドするように設定されています。このため、[[kv_namespaces]]も[[env.production.kv_namespaces]]を定義することでオーバーライドされなければなりません。

これはローカル開発には機能しますが、デプロイを試みると検証に失敗します。

• vars オブジェクト（オプション）

  • Functionをデプロイする際に設定する環境変数のマップです。詳細はEnvironment variablesを参照してください。

• d1_databases オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきD1データベースのリストです。詳細はD1 databasesを参照してください。

• durable_objects オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきDurable Objectsのリストです。詳細はDurable Objectsを参照してください。

• hyperdrive オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきHyperdrive設定を指定します。詳細はHyperdriveを参照してください。

• kv_namespaces オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきKV名前空間のリストです。詳細はKV namespacesを参照してください。

• queues.producers オブジェクト（オプション）

  • このFunctionにバインドされるキューのプロデューサーを指定します。詳細はQueues Producersを参照してください。

• r2_buckets オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきR2バケットのリストです。詳細はR2 bucketsを参照してください。

• vectorize オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきVectorizeインデックスのリストです。詳細はVectorize indexesを参照してください。

• services オブジェクト（オプション）

  • あなたのFunctionがバインドされるべきサービスバインディングのリストです。詳細はservice bindingsを参照してください。

• analytics_engine_datasets オブジェクト（オプション）

  • このFunctionにバインドされる分析エンジンデータセットを指定します。詳細はWorkers Analytics Engineを参照してください。

• ai オブジェクト（オプション）

  • このFunctionにバインドされるAIを指定します。詳細はWorkers AIを参照してください。

限界

あなたのPagesプロジェクトのために限界を設定することができます。これはWorkersのために設定するのと同じ方法です。詳細はこのガイドを参照してください。

バインディング

バインディングは、あなたのPages FunctionsがCloudflare Developer Platform上のリソースと相互作用することを可能にします。バインディングを使用して、あなたのPages FunctionsをKV、Durable Objects、R2、およびD1などのCloudflareリソースと統合します。プロダクション環境とプレビュー環境の両方に対してバインディングを設定できます。

D1データベース

D1はCloudflareのサーバーレスSQLデータベースです。Functionは、D1のクライアントAPIのために各データベースにバインディングを作成することでD1データベース（またはデータベース）をクエリできます。

ノート

Wranglerをデフォルトのローカル開発モードで使用する場合、ファイルはプレビューまたはプロダクションデータベースの代わりにローカルストレージに書き込まれます。詳細はLocal developmentを参照してください。

• D1データベースバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのD1データベースバインディングと相互作用します。

Durable Objects

Durable Objectsは、Workersプラットフォームのための低遅延の調整と一貫したストレージを提供します。

• Durable Object名前空間バインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。

注意

You must create a Durable Object Worker and bind it to your Pages project using the Cloudflare dashboard or your Pages project’s wrangler.toml. You cannot create and deploy a Durable Object within a Pages project.

Pagesプロジェクトのwrangler.tomlに設定されたDurable Objectバインディングにはscript_nameキーが必要です。Workersでは、script_nameキーはオプションです。

• あなたのDurable Object名前空間バインディングと相互作用します。

環境変数

環境変数は、あなたのPages Functionにテキスト文字列やJSON値を添付することを可能にするバインディングの一種です。

• 環境変数をあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたの環境変数と相互作用します。

Hyperdrive

Hyperdriveバインディングは、Pages Function内から任意のPostgresデータベースと相互作用し、クエリを実行することを可能にします。

• Hyperdriveバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。

KV名前空間

Workers KVは、グローバルで低遅延のキー・バリューデータストアです。データは少数の集中データセンターに保存され、その後、アクセス後にCloudflareのデータセンターにキャッシュされます。

ノート

Wranglerをデフォルトのローカル開発モードで使用する場合、ファイルはプレビューまたはプロダクション名前空間の代わりにローカルストレージに書き込まれます。詳細はLocal developmentを参照してください。

• KV名前空間バインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのKV名前空間バインディングと相互作用します。

Queues Producers

QueuesはCloudflareのグローバルメッセージキューサービスで、保証された配信とメッセージバッチ処理を提供します。Queue Producersは、あなたのPages Function内でキューにメッセージを送信することを可能にします。

ノート

現在、Pages Functionsでキューの消費者を設定することはできません。

• Queues Producerバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのQueues Producerバインディングと相互作用します。

R2バケット

Cloudflare R2 Storageは、開発者が通常のクラウドストレージサービスに関連する高額な出口帯域幅料金なしで、大量の非構造化データを保存できるようにします。

ノート

Wranglerをデフォルトのローカル開発モードで使用する場合、ファイルはプレビューまたはプロダクションバケットの代わりにローカルストレージに書き込まれます。詳細はLocal developmentを参照してください。

• R2バケットバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのR2バケットバインディングと相互作用します。

Vectorizeインデックス

Vectorize indexは、意味検索、分類、その他のベクトル検索ユースケースのためにベクトル埋め込みを挿入およびクエリすることを可能にします。

• Vectorizeバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。

サービスバインディング

サービスバインディングは、あなたのPages Function内からWorkerを呼び出すことを可能にします。Pages FunctionをWorkerにバインドすることで、HTTPリクエストをインターネットを介さずにWorkerに送信できます。このリクエストは即座に下流のWorkerを呼び出し、サードパーティサービスへのリクエストと比較してレイテンシを減少させます。詳細はAbout Service bindingsを参照してください。

• サービスバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのサービスバインディングと相互作用します。

Analytics Engine Datasets

Workers Analytics Engineは、Pages Functionsからの分析、可視性、データロギングを提供します。あなたのPages Functionバインディング内でデータポイントを書き込み、そのデータをSQL APIを使用してクエリします。

• Analytics Engine Datasetバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのAnalytics Engine Datasetと相互作用します。

Workers AI

Workers AIは、あなた自身のコードからCloudflareネットワーク上で機械学習モデルを実行することを可能にします。これはWorkers、Pages、またはREST APIを介してどこからでも実行できます。

Workers AI local development usage charges

Using Workers AI always accesses your Cloudflare account in order to run AI models and will incur usage charges even in local development.

他のバインディングとは異なり、このバインディングはPages Functionプロジェクトごとに1つのAIバインディングに制限されています。

• Workers AIバインディングをあなたのwrangler.tomlファイルを介してCloudflare Workersと同じ方法で設定します。
• あなたのWorkers AIバインディングと相互作用します。

ローカル開発設定

あなたが設定できるローカル開発設定は、Pages FunctionsとCloudflare Workersで同じです。詳細はこのガイドを参照してください。

真実の源

あなたのPages Functionsプロジェクトで使用されるとき、あなたのwrangler.tomlファイルは真実の源です。Cloudflareダッシュボードにログインすると、同じフィールドを見ることができますが、編集することはできません。

もしwrangler.tomlを設定に使用したくない場合は、安全に削除して新しいデプロイを作成できます。前回のデプロイからの設定値は引き続き適用され、ダッシュボードから編集することができます。