Cloudflare 環境

Worker の設定ファイルには、複数の Cloudflare 環境 の設定を含められます。 Cloudflare Vite プラグインでは、開発時またはビルド時に環境変数 CLOUDFLARE_ENV を指定して、使う Cloudflare 環境を選びます。 次の Worker 設定ファイルを例にします。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./src/index.ts",
	"vars": {
		"MY_VAR": "Top-level var"
	},
	"env": {
		"staging": {
			"vars": {
				"MY_VAR": "Staging var"
			}
		},
		"production": {
			"vars": {
				"MY_VAR": "Production var"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./src/index.ts"

[vars]
MY_VAR = "Top-level var"

[env.staging.vars]
MY_VAR = "Staging var"

[env.production.vars]
MY_VAR = "Production var"

CLOUDFLARE_ENV=production vite build を実行すると、ビルドが出力する wrangler.json は、'production' Cloudflare 環境向けにフラット化した設定になります。例は次のとおりです。

{
	"name": "my-worker",
	"compatibility_date": "2025-04-03",
	"main": "index.js",
	"vars": { "MY_VAR": "Production var" }
}

MY_VAR の値は Production var です。 このフラット化した設定は、トップレベルのみ、継承可能、継承不可 のキーを組み合わせます。

Cloudflare 環境は開発時にも使えます。 たとえば CLOUDFLARE_ENV=development vite dev を実行できます。 よくある使い方は、既定のトップレベル環境を開発環境にし、必要に応じて環境を追加することです。

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

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

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（もっとも汎用）

Cloudflare 環境 と Vite モード ↗ の考え方を組み合わせたい場合があります。 この方法では、Vite モードで Cloudflare 環境を選び、環境固有の設定とコードを同じ手順で決められます。 先ほどの例を再度使います。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./src/index.ts",
	"vars": {
		"MY_VAR": "Top-level var"
	},
	"env": {
		"staging": {
			"vars": {
				"MY_VAR": "Staging var"
			}
		},
		"production": {
			"vars": {
				"MY_VAR": "Production var"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./src/index.ts"

[vars]
MY_VAR = "Top-level var"

[env.staging.vars]
MY_VAR = "Staging var"

[env.production.vars]
MY_VAR = "Production var"

次に、.env.staging と .env.production ファイルを用意します。

CLOUDFLARE_ENV=staging

CLOUDFLARE_ENV=production

既定では、vite build は 'production' Vite モードを使います。 そのため Vite は .env.production を読み込み、ビルドで使う環境変数を取得します。 .env.production には CLOUDFLARE_ENV=production があるため、Cloudflare Vite プラグインは 'production' Cloudflare 環境を選びます。 その結果、MY_VAR の値は 'Production var' になります。 vite build --mode staging を実行すると、'staging' Vite モードが使われ、'staging' Cloudflare 環境が選ばれます。 その結果、MY_VAR の値は 'Staging var' になります。

Vite での .env ファイルの使い方について詳しくは、関連ドキュメント ↗ を参照してください。