Wrangler 常见陷阱

# Wrangler 常见问题 ## 常见错误 ### "Binding ID vs name mismatch" **原因：** 混淆了绑定名称（代码）和资源 ID **解决方案：** 绑定使用 `binding`（代码名称）和 `id`/`database_id`/`bucket_name`（资源 ID）。预览绑定需要单独的 ID：`preview_id`, `preview_database_id` ### "Environment not inheriting config" **原因：** 不可继承的键未在每个环境中重新定义 **解决方案：** 不可继承的键（绑定、变量）必须在每个环境中重新定义。可继承的键（路由、兼容性日期）可以被覆盖 ### "Local dev behavior differs from production" **原因：** 使用了本地模拟而非远程执行 **解决方案：** 选择合适的远程模式： - `wrangler dev` (默认)：本地模拟，快速，精度有限 - `wrangler dev --remote`：完全远程执行，生产级精度，较慢 - 在测试中使用 `remote: "minimal"` 以通过真实的远程绑定进行快速测试 ### "startWorker doesn't match production" **原因：** 在需要远程资源时使用了本地模式 **解决方案：** 使用 `remote` 选项： typescript const worker = await startWorker({ config: "wrangler.jsonc", remote: true // 或 "minimal" 以加快测试速度 }); ### "Unexpected runtime changes" **原因：** 缺少 `compatibility_date` **解决方案：** 始终设置 `compatibility_date`： c { "compatibility_date": "2025-01-01" } ### "Durable Object binding not working" **原因：** 外部 DO 缺少 `script_name` **解决方案：** 始终为外部 Durable Objects 指定 `script_name`： c { "durable_objects": { "bindings": [ { "name": "MY_DO", "class_name": "MyDO", "script_name": "my-worker" } ] } } 对于同一 Worker 中的本地 DO，`script_name` 是可选的。 ### "Auto-provisioned resources not appearing" **原因：** ID 在首次部署时写回配置，但配置未重新加载 **解决方案：** 在首次使用自动配置部署后，配置文件会更新 ID。提交更新后的配置。在后续部署中，将复用现有资源。 ### "Secrets not available in local dev" **原因：** 通过 `wrangler secret put` 设置的密钥仅在已部署的 Worker 中有效 **解决方案：** 对于本地开发，使用 `.dev.vars` ### "Node.js compatibility error" **原因：** 缺少 Node.js 兼容性标志 **解决方案：** 某些绑定（如带有 `pg` 的 Hyperdrive）需要： c { "compatibility_flags": ["nodejs_compat_v2"] } ### "Workers Assets 404 errors" **原因：** 资源路径不匹配