环境变量矩阵与排错 FAQ
本页汇总 wrangler.jsonc 绑定、明文 vars 与 wrangler secret 密钥的完整校验规则,并解释 /healthz 健康探针为何与发信请求保持完全一致的失败关闭口径。
环境变量与绑定矩阵
非密配置放在 wrangler.jsonc(或 wrangler.local.jsonc)的 vars 段落,敏感令牌与 IP 名单通过 .dev.vars(本地)或 wrangler secret put(线上)注入:
| 变量 / 绑定名 | 类型与保密要求 | 默认值与合法条件 | 过渡别名(旧名兼容) |
|---|---|---|---|
EMAIL | send_email 平台绑定 | 必填,必须可调用 EMAIL.send(...) | 无 |
RATE_LIMITER | ratelimits 可选绑定 | 不配置时不限流;一旦配置就必须具备 limit 方法,否则整体报错 503 | 无 |
AUTH_TOKENS | 加密环境变量(逗号分隔) | 至少 1 把令牌,自动去重;每把仅限 [A-Za-z0-9._~+/=-] 且长度 32–512 | AUTH_TOKEN、WEBHOOK_TOKEN |
ALLOWED_SENDER_DOMAINS | 普通环境变量(逗号分隔) | 至少 1 个合法域名;*.example.com 只匹配子域,不匹配裸域 example.com | SENDER_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。
可行的应对方式有两种:
- 关闭白名单检查,保留令牌与限流防线:设置
IP_ALLOWLIST_ENABLED=0。此时服务仍强制校验请求头中存在 Cloudflare 边缘注入的CF-Connecting-IP,且每次发信请求都会打印一条ip_allowlist_disabled警告日志,方便运维审计;建议同时在配置里挂载RATE_LIMITER绑定。 - 通过自建固定出口代理收敛流量:让 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 代表有意关闭或名单读失败) | 否(有意关闭不等于故障) |
emailBinding | EMAIL 绑定存在且具备 send 函数 | 是 |
rateLimiter | RATE_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。