Secrets

Secrets 是一种绑定类型，允许您将加密的文本值附加到 Worker。Secrets 用于存储 API 密钥和身份验证 token 等敏感信息。

您可以通过以下方式在 Worker 代码中访问 secrets：

• 传递给 Worker fetch 事件处理程序 的 env 参数。
• 从 cloudflare:workers 导入 env，以便在代码的任何位置访问 secrets。
• 在启用了 Node.js 兼容性 的 Workers 中使用 process.env。

Secrets 可以像任何其他环境变量一样从 Workers 访问。例如，给定 DB_CONNECTION_STRING secret，您可以通过 env 参数在 Worker 代码中访问它：

import postgres from "postgres";

export default {
	async fetch(request, env, ctx) {
		const sql = postgres(env.DB_CONNECTION_STRING);

		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

您还可以从 cloudflare:workers 导入 env，以便在代码的任何位置（包括请求处理程序之外）访问 secrets：

import { env } from "cloudflare:workers";
import postgres from "postgres";

// Initialize the database client at the top level using a secret
const sql = postgres(env.DB_CONNECTION_STRING);

export default {
	async fetch(request) {
		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

import { env } from "cloudflare:workers";
import postgres from "postgres";

// Initialize the database client at the top level using a secret
const sql = postgres(env.DB_CONNECTION_STRING);

export default {
	async fetch(request: Request): Promise<Response> {
		const result = await sql`SELECT * FROM products;`;

		return new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

有关全局访问 env 的更多详细信息，请参阅将 env 作为全局变量导入。

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

您可以使用 Wrangler 配置中的 secrets 配置属性 声明 Worker 所需的 secret 名称。定义后，如果 Worker 上未配置任何必需的 secrets，wrangler deploy 和 wrangler versions upload 将失败并显示清晰的错误。

可以通过 wrangler secret put 或 wrangler versions secret put 命令添加 secrets。

wrangler secret put 会创建 Worker 的新版本并立即部署。

npx wrangler secret put <KEY>

如果使用渐进式部署，请改用 wrangler versions secret put 命令。这只会创建 Worker 的新版本，然后可以使用 wrangler versions deploy 部署。

npx wrangler versions secret put <KEY>

要通过仪表板添加 secret：

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

   Go to Workers & Pages ↗

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

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

4. 选择 Secret（密钥） 类型，输入 Variable name（变量名称），并输入 Value（值）。此 secret 将对 Worker 可用，但其值在 Wrangler 和仪表板中会被隐藏。

5. （可选）要添加更多 secrets，选择 Add variable（添加变量）。

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

您可以使用 wrangler deploy 或 wrangler versions upload 上的 --secrets-file 标志在上传 Worker 代码的同时上传 secrets。这接受 JSON 或 .env 文件路径——与 wrangler secret bulk 接受的格式相同。每个 bulk 请求最多可为单个版本上传 100 个 secrets。

npx wrangler deploy --secrets-file .env.production

npx wrangler versions upload --secrets-file secrets.json

文件中未包含的 secrets 会从上一版本保留。这在 CI/CD 流水线中很有用，您希望在一次操作中部署代码并更新 secrets。

可以通过 wrangler secret delete 或 wrangler versions secret delete 命令删除 secrets。

wrangler secret delete 会创建 Worker 的新版本并立即部署。

npx wrangler secret delete <KEY>

如果使用渐进式部署，请改用 wrangler versions secret delete 命令。这只会创建 Worker 的新版本，然后可以使用 wrangler versions deploy 部署。

npx wrangler versions secret delete <KEY>

要通过仪表板从 Worker 项目中删除 secret：

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

   Go to Workers & Pages ↗

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

3. 在 Variables and Secrets（变量和密钥） 下，选择 Edit（编辑）。

4. 在 Edit（编辑） 抽屉中，选择要删除的 secret 旁的 X。

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

6. （可选）除了使用编辑抽屉，您还可以点击 secret 旁的删除图标。

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

• Wrangler secret 命令 - 查看用于创建、删除和列出 secrets 的 Wrangler 命令。
• secrets 配置属性 - 在 Wrangler 配置中声明所需的 secret 名称。用于本地开发和部署期间的验证，以及类型生成的真实来源。
• Cloudflare Secrets Store - 加密并存储敏感信息作为 secrets，可在整个账户中安全复用。