Workers 里 vars 和 secrets 有什么区别？

在 Worker 的代码里，vars 和 secret 看不出任何区别，都是 env.X。区别出在代码之外：你的配置文件、git 历史和 dashboard。

能公开的配置放 vars，任何凭据放 secret。 vars 是明文，写在配置文件里，会进 git，在 dashboard 里可见；secret 设置后，在 wrangler 和 dashboard 里都不再显示。官方文档明确警告不要把敏感信息放进 vars。

之所以说「对 Worker 一样，对人不一样」，是因为选错的代价全落在人这一侧：secret 误放进 vars 就进了 git 历史，之后只能轮换，无法撤回。下面讲 secret 怎么写入、怎么声明它必须存在，以及有哪些限额。

secret 怎么写入？

用 wrangler secret put <KEY> 写入，它会创建新版本并立即部署。想只创建版本、不立即生效，用 wrangler versions secret put。这两条是官方文档的说法，我没有执行过，因为它们会改动线上资源。

vars 和 secrets 会出现在 process.env 里吗？

会，有条件。官方说明，开启 nodejs_compat 并启用 nodejs_compat_populate_process_env（兼容性日期 2025-04-01 及以后默认启用）时，vars 和 secrets 也会出现在全局 process.env 里。

有一个我在本地确认过的差别：兼容性日期 2026-10-01、没有写任何标志时，JSON 对象型的 vars 在 env 里仍是对象，在 process.env 里则是字符串。别混着用，选一种读法并坚持下去。

怎么声明「这个 Worker 必须有哪些 secret」？

配置里有 secrets.required。官方说明它在本地开发和 wrangler deploy、wrangler versions upload 时校验，并作为 wrangler types 生成类型的来源。

我在本地试过：

"secrets": { "required": ["API_KEY", "DB_PASSWORD"] }

.dev.vars 里只有 API_KEY 和一个未声明的 EXTRA。结果是 wrangler types 生成了这两个必需的 secret 类型，不含 EXTRA；wrangler dev 启动时警告 Missing required secrets: DB_PASSWORD。deploy 时校验失败会怎样，我没有验证，只有官方文档的说法。

vars 和 secrets 有数量和大小限制吗？

有。官方限额页写的是：每个 Worker 的变量总数（secrets 加文本变量）免费版 64、付费版 128，单个变量大小 5 KB。大块配置不要塞进变量，放 KV 或 R2。

本地开发时这些 secret 放在哪、会不会覆盖配置里的 vars，见 wrangler dev 本地和线上差在哪。绑定与配置的整体关系见 Workers 的绑定是什么。

process.env 里对象型 vars 变成字符串、secrets.required 的类型生成与缺失警告，我在 wrangler 4.151.3（workerd 2026-10-19）的 wrangler dev --local 上跑过。可见性规则、wrangler secret put 与 wrangler versions secret put 的行为、process.env 的默认启用日期、deploy 时的校验失败，以及变量数量和大小限额，来自 2026-10 的官方文档，我没有复现。限额会变化，以官方文档为准。本文没有执行任何会改动线上资源的命令。参考：环境变量与 secrets。