環境変数

環境変数はバインディングの一種で、テキスト文字列や JSON 値を Worker に付けられます。環境変数は、Worker の fetch イベントハンドラー に渡される env パラメーター から使えます。

テキスト文字列と JSON 値は暗号化されません。アプリケーションの設定値の保存に向いています。

Wrangler で環境変数を追加するには、Wrangler ファイルの [vars] 設定でテキストと JSON を定義します。次の例では、API_HOST と API_ACCOUNT_ID がテキスト値、SERVICE_X_DATA が JSON 値です。

{
	"$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

Worker コードから API_HOST 環境変数にアクセスする例は次のとおりです。

export default {
	async fetch(request, env, ctx) {
		return new Response(`API host: ${env.API_HOST}`);
	},
};

export interface Env {
	API_HOST: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response(`API host: ${env.API_HOST}`);
	},
} satisfies ExportedHandler<Env>;

from workers import WorkerEntrypoint, Response

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        # Environment variables are accessed via attribute access on self.env
        return Response(f"API host: {self.env.API_HOST}")

cloudflare:workers から env をインポートすると、リクエストハンドラーの外を含む、コードの任意の場所から環境変数にアクセスできます。

import { env } from "cloudflare:workers";

// Access environment variables at the top level
const apiHost = env.API_HOST;

export default {
	async fetch(request) {
		return new Response(`API host: ${apiHost}`);
	},
};

import { env } from "cloudflare:workers";

// Access environment variables at the top level
const apiHost = env.API_HOST;

export default {
	async fetch(request: Request): Promise<Response> {
		return new Response(`API host: ${apiHost}`);
	},
};

この方法は、次の場合に便利です。

• Worker のトップレベルで設定や API クライアントを初期化する。
• ネストの深い関数から、毎回 env を渡さずに環境変数へアクセスする。

詳細は グローバルとして env をインポートする を参照してください。

Wrangler の環境 を使うと、同じ Worker に対して環境ごとに異なる設定を指定できます。vars の値も環境ごとに変えられます。 vars は 継承されないキー です。環境には継承されないため、環境ごとに指定する必要があります。

次の例では、staging と production の 2 つの環境を用意し、API_HOST にそれぞれ異なる値を設定しています。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker-dev",
	// top level environment
	"vars": {
		"API_HOST": "api.example.com"
	},
	"env": {
		"staging": {
			"vars": {
				"API_HOST": "staging.example.com"
			}
		},
		"production": {
			"vars": {
				"API_HOST": "production.example.com"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker-dev"

[vars]
API_HOST = "api.example.com"

[env.staging.vars]
API_HOST = "staging.example.com"

[env.production.vars]
API_HOST = "production.example.com"

特定の環境で Wrangler コマンドを実行するには、--env または -e フラグを渡します。たとえば、staging という環境で Worker を開発するには npx wrangler dev --env staging を実行し、デプロイは npx wrangler deploy --env staging で行います。

Wrangler の環境 を参照してください。

ダッシュボードから環境変数を追加するには、次の手順を実行します。

1. Cloudflare ダッシュボードで Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Overview で Worker を選びます。

3. Settings を選びます。

4. Variables and Secrets で Add を選びます。

5. Type を選び、Variable name と Value を入力します。この変数は Worker から利用できます。

6. （任意）環境変数を追加する場合は Add variable を選びます。

7. Deploy を選び、変更を反映します。

シークレット は 環境変数 です。違いは、定義したあと Wrangler や Cloudflare ダッシュボードではシークレットの値が表示されないことです。そのため、パスワードや API トークンなどの機密データは、漏洩を防ぐために常に暗号化する必要があります。Worker から見ると、環境変数とシークレットに違いはありません。シークレットの値は、定義したとおりに渡されます。

ローカル開発で使うシークレットは、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（もっとも汎用）

nodejs_compat と nodejs_compat_populate_process_env 互換フラグ（互換日付が 2025-04-01 以降の場合は既定で有効）を有効にすると、グローバルな process.env から環境変数を使えます。

process.env は、Worker 内で初めて process にアクセスしたときに遅延して埋められます。

テキスト変数の値はそのまま公開されます。

文字列に評価される JSON 変数は、パース後の値として公開されます。

文字列に評価されない JSON 変数は、生の JSON 文字列として公開されます。

たとえば、テキスト値 2 つと JSON 値 1 つの、3 つの環境変数を持つ Worker を考えます。

[vars]
FOO =  "abc"
BAR =  "abc"
BAZ = { "a": 123 }

環境変数は、wrangler.{json|jsonc|toml} ファイル、または Cloudflare ダッシュボードの UI から追加できます。

process.env.FOO と process.env.BAR の値は、それぞれ JavaScript 文字列 "abc" です。

process.env.BAZ の値は、JSON エンコードされた文字列 "{ \"a\": 123 }" です。

• Service Worker 形式から ES modules 構文への環境変数の移行