环境变量

您可以添加环境变量（一种绑定类型），将文本字符串或 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，并为 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 标志。例如，您可以通过运行 npx wrangler dev --env staging 在名为 staging 的环境中开发 Worker，并使用 npx wrangler deploy --env staging 部署。

了解 Wrangler 中的环境。

要通过仪表板添加环境变量：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择您的 Worker。

3. 选择 Settings（设置）。

4. 在 Variables and Secrets（变量和密钥） 下，选择 Add（添加）。

5. 选择 Type（类型），输入 Variable name（变量名称），并输入 Value（值）。此变量将对 Worker 可用。

6. （可选）要添加多个环境变量，选择 Add variable（添加变量）。

7. 选择 Deploy（部署） 以应用更改。

Secrets 是环境变量。区别在于 secret 值在你定义后不会在 Wrangler 或 Cloudflare 仪表板中可见。这意味着敏感数据（包括密码或 API 令牌）应始终加密以防止数据泄露。对你的 Worker 而言，环境变量和 secret 没有区别。secret 的值会按定义传递。

将本地开发使用的 secrets 放在 .dev.vars 文件或 .env 文件中，与 Wrangler 配置文件位于同一目录。

这些文件应使用 dotenv ↗ 语法格式化。例如：

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

要为每个 Cloudflare 环境设置不同的 secrets，请创建名为 .dev.vars.<environment-name> 或 .env.<environment-name> 的文件。

在本地开发中选择 Cloudflare 环境时，会先加载对应的环境特定文件，再加载通用的 .dev.vars（或 .env）文件。

• 使用 .dev.vars.<environment-name> 文件时，每个环境必须定义所有 secrets。如果存在 .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 字符串暴露。

例如，假设 Worker 有三个环境变量，两个文本值和一个 JSON 值：

[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 }"。

:::note 另请注意，由于 secrets 是运行时中环境变量的一种形式，secrets 也会通过 process.env 暴露。

• 从 Service Worker 格式迁移到 ES modules 语法 中的环境变量。