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-08-17",
	"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-08-17"
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。 通常将默认顶层环境用作开发环境，然后根据需要添加其他环境。

将本地开发使用的 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（最不特定）

你可能希望结合 Cloudflare 环境 与 Vite 模式 ↗ 的概念。 采用这种方式时，Vite 模式可用于选择 Cloudflare 环境，并可用单一方法确定特定于环境的配置和代码。 再次考虑前面的示例：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"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-08-17"
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 文件的更多信息，请参阅相关文档 ↗。