Wrangler 自定义请求头怎么设？JSON 格式与受保护头

先确认版本和请求去向

Cloudflare 于 2026 年 11 月 11 日发布说明：Wrangler 4.160.0 与 Cloudflare CLI（cf）1.0.0-beta.29 支持自定义 Cloudflare API 请求头。这里的 cf 是 beta 版本，不应把版本号写成稳定版 1.0 已正式发布。

这项配置针对命令行工具访问 Cloudflare API 的请求。若你想修改 Worker 业务请求、网站响应头、OAuth 登录请求或本地模拟流量，应先核对对应功能；不能因为工具读取了环境变量，就认为所有 HTTP 流量都会带上它。公告与参考文档没有给出这项功能的独立费用、套餐或国家清单，具体账号权限仍按现有产品规则。

把头名和字符串值写进一个 JSON 对象

官方参考要求将 CLOUDFLARE_API_HEADERS 设置为 JSON 对象，每个 HTTP 头名对应一个字符串值。下面沿用官方的非敏感示例 X-Custom-Header: value；它只说明配置写法，不代表本文已运行命令或验证某个账号。

Bash/Zsh：export CLOUDFLARE_API_HEADERS='{"X-Custom-Header":"value"}'

PowerShell：$env:CLOUDFLARE_API_HEADERS = '{"X-Custom-Header":"value"}'

然后由同一环境中的 Wrangler 或 cf 命令读取该变量。外层单引号保留内部 JSON 的双引号；不要把 JSON 写成 JavaScript 对象，也不要把需要字符串的位置写成未加引号的数字或布尔值。若 CI 中效果不同，先核对变量是否实际传给运行工具的步骤，而不是复制一份带真实认证值的环境快照。

Host 和 Content-Type 为什么不能覆盖

官方文档明确保护以下九个头：Host、Content-Type、Content-Encoding、Content-Length、Connection、Transfer-Encoding、Upgrade、TE、Trailer。它们涉及请求主体或传输行为，不能通过 CLOUDFLARE_API_HEADERS 设置。

头名不区分大小写，改成 host 或 CONTENT-TYPE 不会得到另一种权限。排查时先把需要添加的业务元数据与这些受保护头分开；本文不推定每种不合规输入的具体错误码，也不建议用改写请求头来绕开这一边界。

认证突然失败，先看是否覆盖了原来的头

对于可配置的头，变量中的值会覆盖请求里已有的同名值，官方特别说明其中包括认证头。因此，原有认证配置本来有效，也可能被自定义对象里的另一个值取代；只检查 API token 的原始配置，可能找不到冲突。

先在本地核对自定义对象是否包含认证头，以及它是否确实属于预期请求。用于诊断的非敏感标签不需要顺带覆盖认证；保留现有授权范围，不把真实 token 写进文章、截图或公共日志。更换代理出口不会修正已经发送的错误认证值，也不会扩大账号的 API 权限。

按适用范围做最小验证，再清理临时配置

建议按顺序检查：工具版本、运行进程可见的环境变量、JSON 的键值类型、是否触及受保护头、是否覆盖认证，最后确认目标是不是 Cloudflare API。官方明确排除本地模拟和 OAuth 请求，所以这两类请求没有变化，不能单独证明变量配置失败。

如需自行验证，应选择自己已有权限且符合现有变更规则的操作，记录实际响应；不要仅凭环境变量设置成功，就判定远端已经收到请求头。结束临时诊断后，在相同 shell 或 CI 配置中移除不再需要的变量。本文仅核对官方公开说明，没有执行部署、API 调用或连接测试，也没有测得性能或成功率。