跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

环境

最后更新 查看 MarkdownAgent 设置

Wrangler 允许你使用环境为同一 Worker 应用程序创建不同的配置。环境在 Worker 的 Wrangler 配置文件 中配置。

创建环境时，Cloudflare 实际上会创建一个名为 <top-level-name>-<environment-name> 的新 Worker。例如，名为 my-worker 且环境为 dev 的 Worker 项目将部署为名为 my-worker-dev 的 Worker。

请查看以下环境流程：

  1. 创建一个 Worker，例如 my-worker。

  2. 在 Worker 的 Wrangler 配置文件 中创建环境，例如 dev，方法是添加 [env.<ENV_NAME>] 部分。

    {
	"name": "my-worker",
	"env": {
		"<ENV_NAME>": {
			// environment-specific configuration goes here
		}
	}
}
    name = "my-worker"

[env]
"<ENV_NAME>" = { }

  3. 你可以为 dev 环境配置与顶层环境不同的值。有关不同选项如何在环境之间继承——或不继承——的说明，请参阅此处。 例如，为 dev 环境中的 Worker 设置不同的路由：

    {
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "your-worker",
	"route": "example.com",
	"env": {
		"dev": {
			"route": "dev.example.com",
		},
	},
}
    "$schema" = "./node_modules/wrangler/config-schema.json"
name = "your-worker"
route = "example.com"

[env.dev]
route = "dev.example.com"

  4. 环境在 Wrangler 命令中与 --env 或 -e 标志一起使用。例如，你可以通过运行 npx wrangler dev -e=dev 在 dev 环境中开发 Worker，并使用 npx wrangler deploy -e=dev 部署它。

    或者，你可以使用 CLOUDFLARE_ENV 环境变量 选择活动环境。例如，CLOUDFLARE_ENV=dev npx wrangler deploy 将部署到 dev 环境。--env 命令行参数优先于 CLOUDFLARE_ENV 环境变量。

不可继承的键与环境

不可继承的键可在顶层配置，但不能被环境继承，必须为每个环境单独指定。

例如，绑定（binding）和环境变量不可继承，必须在 Wrangler 配置文件 中为每个环境单独指定。

请查看以下 Wrangler 文件示例：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"vars": {
		"API_HOST": "example.com",
	},
	"kv_namespaces": [
		{
			"binding": "<BINDING_NAME>",
			"id": "<KV_NAMESPACE_ID_DEV>",
		},
	],
	"env": {
		"production": {
			"vars": {
				"API_HOST": "production.example.com",
			},
			"kv_namespaces": [
				{
					"binding": "<BINDING_NAME>",
					"id": "<KV_NAMESPACE_ID_PRODUCTION>",
				},
			],
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"

[vars]
API_HOST = "example.com"

[[kv_namespaces]]
binding = "<BINDING_NAME>"
id = "<KV_NAMESPACE_ID_DEV>"

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

[[env.production.kv_namespaces]]
binding = "<BINDING_NAME>"
id = "<KV_NAMESPACE_ID_PRODUCTION>"

服务绑定

要使用指向特定环境中 Worker 的服务绑定，需要在 service 字段中将环境名称附加到目标 Worker 名称。格式应为 <worker-name>-<environment-name>。 在下面的示例中，我们有两个 Worker，都有 staging 环境。worker-b 有一个指向 worker-a 的服务绑定。请注意 staging 环境中的 service 字段如何指向 worker-a-staging，而顶层服务绑定指向 worker-a。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker-a",
	"vars": {
		"FOO": "<top-level-var>",
	},
	"env": {
		"staging": {
			"vars": {
				"FOO": "<staging-var>",
			},
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-a"

[vars]
FOO = "<top-level-var>"

[env.staging.vars]
FOO = "<staging-var>"
{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "worker-b",
	"services": {
		"binding": "<BINDING_NAME>",
		"service": "worker-a",
	},
	// Note how `service = "worker-a-staging"`
	"env": {
		"staging": {
			"service": {
				"binding": "<BINDING_NAME>",
				"service": "worker-a-staging",
			},
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "worker-b"

[services]
binding = "<BINDING_NAME>"
service = "worker-a"

[env.staging.service]
binding = "<BINDING_NAME>"
service = "worker-a-staging"

生产环境的密钥

你可以通过运行 wrangler secret put <KEY> -env 命令来分配特定于环境的密钥。你也可以创建名为 .dev.vars.<environment-name> 的 dotenv 类型文件。

与其他环境变量一样，密钥不可继承，必须为每个环境单独定义。

本地开发中的密钥

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

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

.dev.vars / .envbash
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（最不特定）

示例

预发布和生产环境

以下 Wrangler 文件向 Wrangler 文件添加两个环境 [env.staging] 和 [env.production]。如果你部署到自定义域（Custom Domain）或路由，必须为每个环境提供 route 或 routes 键。

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"route": "dev.example.com/*",
	"vars": {
		"ENVIRONMENT": "dev",
	},
	"env": {
		"staging": {
			"vars": {
				"ENVIRONMENT": "staging",
			},
			"route": "staging.example.com/*",
		},
		"production": {
			"vars": {
				"ENVIRONMENT": "production",
			},
			"routes": ["example.com/foo/*", "example.com/bar/*"],
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
route = "dev.example.com/*"

[vars]
ENVIRONMENT = "dev"

[env.staging]
route = "staging.example.com/*"

  [env.staging.vars]
  ENVIRONMENT = "staging"

[env.production]
routes = [ "example.com/foo/*", "example.com/bar/*" ]

  [env.production.vars]
  ENVIRONMENT = "production"

你可以通过 --env 标志传递环境名称，在特定环境中运行命令。

使用此配置，Wrangler 的行为如下：

npx wrangler deploy
Uploaded my-worker
Published my-worker
  dev.example.com/*
npx wrangler deploy --env staging
Uploaded my-worker-staging
Published my-worker-staging
  staging.example.com/*
npx wrangler deploy --env production
Uploaded my-worker-production
Published my-worker-production
  example.com/*

任何已定义的环境变量（vars 键）都可以通过 Worker 中的 env 对象 访问。

使用此配置，env.ENVIRONMENT 变量可用于根据给定环境调用特定代码：

export default {
	async fetch(request, env, ctx) {
		if (env.ENVIRONMENT === "staging") {
			// staging-specific code
		} else if (env.ENVIRONMENT === "production") {
			// production-specific code
		}
	},
};

使用 *.workers.dev 的预发布环境

要将代码部署到 *.workers.dev 子域，在所需环境中包含 workers_dev = true。你的 Wrangler 文件可能如下所示：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-worker",
	"route": "example.com/*",
	"env": {
		"staging": {
			"workers_dev": true,
		},
	},
}
"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
route = "example.com/*"

[env.staging]
workers_dev = true

使用此配置，Wrangler 的行为如下：

npx wrangler deploy
Uploaded my-worker
Published my-worker
  example.com/*
npx wrangler deploy --env staging
Uploaded my-worker
Published my-worker
  https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev

这篇文档对您有帮助吗？