Skip to content

环境变量矩阵与排错 FAQ ​

本页汇总 wrangler.jsonc 绑定、明文 vars 与 wrangler secret 密钥的完整校验规则,并解释 /healthz 健康探针为何与发信请求保持完全一致的失败关闭口径。

环境变量与绑定矩阵 ​

非密配置放在 wrangler.jsonc(或 wrangler.local.jsonc)的 vars 段落,敏感令牌与 IP 名单通过 .dev.vars(本地)或 wrangler secret put(线上)注入:

变量 / 绑定名类型与保密要求默认值与合法条件过渡别名(旧名兼容)
EMAILsend_email 平台绑定必填,必须可调用 EMAIL.send(...)无
RATE_LIMITERratelimits 可选绑定不配置时不限流;一旦配置就必须具备 limit 方法,否则整体报错 503无
AUTH_TOKENS加密环境变量(逗号分隔)至少 1 把令牌,自动去重;每把仅限 [A-Za-z0-9._~+/=-] 且长度 32–512AUTH_TOKEN、WEBHOOK_TOKEN
ALLOWED_SENDER_DOMAINS普通环境变量(逗号分隔)至少 1 个合法域名;*.example.com 只匹配子域,不匹配裸域 example.comSENDER_DOMAIN
IP_ALLOWLIST加密环境变量(逗号分隔)支持 IPv4、IPv6 与 CIDR(不填前缀按 /32 或 /128);开启检查时留空触发 503*(早期关闭写法)
IP_ALLOWLIST_ENABLED普通环境变量开关留空默认开启;真值 1/true/yes/on,假值 0/false/no/off(大小写不敏感)无
MAX_RECIPIENTS普通环境变量缺省 10,必须为 1 到 50 之间的正整数(覆盖 to + cc + bcc 总和)无

关掉 IP 检查时白名单仍会被解析

当 IP_ALLOWLIST_ENABLED=0 但 IP_ALLOWLIST 仍保留历史内容时,loadConfig 依然会对名单做语法解析;同时不允许出现 IP_ALLOWLIST="*" 与 IP_ALLOWLIST_ENABLED=1 并存的矛盾配置。这样可以保证白名单重新打开时不会潜伏语法炸弹。

动态出口 CI 约束与应对方案 ​

如果调用方中包含托管在公有云上的持续集成流水线容器,其出口 IP 会随调度器扩缩容动态漂移;把公有云出口大网段加入 IP_ALLOWLIST 等同于向公网开放白名单,且会导致间歇性 403。

可行的应对方式有两种:

  1. 关闭白名单检查,保留令牌与限流防线:设置 IP_ALLOWLIST_ENABLED=0。此时服务仍强制校验请求头中存在 Cloudflare 边缘注入的 CF-Connecting-IP,且每次发信请求都会打印一条 ip_allowlist_disabled 警告日志,方便运维审计;建议同时在配置里挂载 RATE_LIMITER 绑定。
  2. 通过自建固定出口代理收敛流量:让 CI Runner 经拥有静态公网 IP 的自有代理转发请求,再把该固定 IP 填入 IP_ALLOWLIST。

/healthz 七项就绪体检语义 ​

GET /healthz 与 HEAD /healthz(支持 curl -I 探针)调用 inspectConfig(env),与请求主路径共享同一批校验读取器。只要任意必填项缺失、取值语法损坏,或选配的 RATE_LIMITER 绑定不可调用,接口就返回 503 not_configured 而非用 200 掩盖故障;响应里只包含布尔状态,绝不回显配置取值。

checks 字段为 true 的条件false 时是否拉垮就绪(503)
config令牌、发件域、IP 配置与 MAX_RECIPIENTS 四项整体解析通过是
authTokens至少有 1 把合规令牌(含别名)是
senderDomains至少有 1 个合法发件域(含别名)是
ipAllowlist来源配置有效(开启时名单非空且全部合法;关闭时允许为空,非空则需全部合法)是
ipAllowlistEnforced来源检查当前处于实际拦截状态(false 代表有意关闭或名单读失败)否(有意关闭不等于故障)
emailBindingEMAIL 绑定存在且具备 send 函数是
rateLimiterRATE_LIMITER 已配置且具备 limit 函数(未配置时为 false)否(未配正常,配坏则 ready=false)

部署与运行排错 FAQ ​

报错现象常见根因排查命令 / 方式解决方案
/healthz 与 /v1/send 全返回 503 not_configured漏配 AUTH_TOKENS / ALLOWED_SENDER_DOMAINS,开启白名单时 IP_ALLOWLIST 为空,或名单含非法条目(如 nope、前缀 /99、带 %eth0 zone id)请求 GET /healthz 看 error.details.checks 哪一项为 false;线上看 wrangler tail 的 configuration_error 日志用 wrangler secret put 补全或修正对应变量;若不启用 IP 白名单请显式设 IP_ALLOWLIST_ENABLED=0
发信返回 502 upstream_failed① 代码放行了 ALLOWED_SENDER_DOMAINS,但 wrangler.jsonc 的 send_email 未列明或未在平台验证收发地址;② 在本地 wrangler dev 运行核对响应中截断的 error.details.providerCode 与 wrangler.jsonc 的 allowed_sender_addresses / allowed_destination_addresses在 Cloudflare 控制台验证收发地址并同步更新本地部署配置中的 send_email 列表;本地仿真到达此步属正常行为
已设 IP_ALLOWLIST_ENABLED=0 仍报 403 forbidden请求未经过 Cloudflare 边缘或本地直连测试未带 CF-Connecting-IP 头检查测试命令是否缺少边缘代理头,或服务是否未经过 Cloudflare 代理层线上确保走 Cloudflare Workers 路由;本地调试若需测试请确保调试网关/测试夹具注入来源头
中文 Windows 终端调用返回 400 invalid_request(must be valid UTF-8)Windows Shell 默认编码发出的命令行内联 JSON 含非 UTF-8 字节检查报错 error.message 是否含 UTF-8将 JSON 正文存为 UTF-8 文件后改用 curl --data-binary @payload.json 提交
本地 pnpm run dev 启动崩溃报错 Incorrect type for map entry在入口文件 src/index.ts 新增了具名 export(如常量或辅助函数),Workers 把非 default 导出当成 handler检查 src/index.ts 的导出列表将共享常量与工具函数移至其他模块,src/index.ts 只保留 export default { fetch }

若要对接 HTTP 接口并查看标准报文与错误码完整列表,请前往 HTTP 契约、安全边界与扩展 FAQ。