Cloudflare Workers 环境变量与密钥管理

上一章的 CRUD 接口还没接入真实数据，这一章先解决一个基础但重要的问题，如何安全地管理配置和密钥。真实项目里 API 密钥、数据库连接信息等敏感数据，绝不能直接写在代码里。

为什么不能硬编码

// 反面教材，绝对不要这么写
const API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxx";

硬编码密钥的风险有三条。第一，代码提交到 Git 仓库后密钥就永久留在历史记录里，一旦仓库公开就等于泄露。第二，即使仓库是私有的，任何拿到代码的人都能直接看到。第三，密钥更换时必须改代码重新部署，非常麻烦。

正确做法是把敏感信息放到平台侧，代码里只留一个占位名。

两类配置的区别

Workers 把配置分成普通环境变量和加密密钥两类

普通变量给谁都行，密钥必须保密，这个划分要记牢。

代码中读取环境变量

所有环境变量都通过 fetch 函数的第二个参数 env 读取，普通变量和密钥的读取方式完全一样

export default {
  async fetch(request, env, ctx) {
    const name = env.SITE_NAME;      // 普通变量
    const apiKey = env.API_KEY;      // 密钥
    return Response.json({ name });
  },
};

普通环境变量配置

在 wrangler.toml 中添加 [vars] 段

name = "my-worker"
main = "src/index.js"
compatibility_date = "2026-01-01"

[vars]
SITE_NAME = "我的网站"
FEATURE_ENABLED = "true"

保存后运行 wrangler dev，代码里就能通过 env.SITE_NAME 读取到值。

也可以直接在仪表盘配置。进入 Worker 的 设置 页面，找到 变量和机密 区域，添加普通变量即可，效果与配置文件一致。

加密密钥配置

密钥不能在配置文件里明文书写，要用专门的命令设置

wrangler secret put API_KEY

命令执行后会提示输入密钥值，输入后回车确认，密钥即加密保存到线上。也可以在仪表盘的 变量和机密 区域添加机密类型的变量。

注意，wrangler secret put 设置的密钥只在线上生效，本地开发时还需要单独配置。

本地开发变量

本地运行时，环境变量和密钥统一写在一个 .dev.vars 文件里，这个文件在项目根目录，格式为

SITE_NAME = "本地网站"
API_KEY = "local-dev-key"

.dev.vars 的内容会被 wrangler dev 自动加载，行为和线上一致。因为文件里可能包含密钥，必须把它加入 .gitignore，绝不能被提交到仓库。C3 生成的项目默认已排除这个文件。

多环境配置

开发环境、生产环境经常需要不同的配置值。Wrangler 支持按环境拆分配置，在 wrangler.toml 中添加环境段

name = "my-worker"
main = "src/index.js"
compatibility_date = "2026-01-01"

[vars]
SITE_NAME = "开发环境"

[env.production]
vars = { SITE_NAME = "生产环境" }

部署到指定环境

# 默认环境
wrangler deploy

# 生产环境
wrangler deploy --env production

对应的，密钥也可以分环境设置

wrangler secret put API_KEY --env production

多环境方案能避免”改完代码忘记切换配置”这类低级事故，是团队协作的标配。

安全建议清单

收尾总结几条必须遵守的规则

至此基础设施部分结束。从下一篇开始进入数据存储，先学 KV 分布式键值存储。

上一篇 Cloudflare Workers 路由与 API 开发
下一篇 Cloudflare Workers KV 存储