Workerd 常见陷阱

# Workerd 常见问题与陷阱 ## 常见错误 ### "Missing compatibility date" (缺少兼容性日期) **原因:** 未设置兼容性日期 **解决方案:** ❌ 错误: capnp const worker :Workerd.Worker = ( serviceWorkerScript = embed "worker.js" ) ✅ 正确: capnp const worker :Workerd.Worker = ( serviceWorkerScript = embed "worker.js", compatibilityDate = "2024-01-15" # 务必设置！ ) ### 错误的绑定类型 **问题:** JSON 未被解析 **原因:** 使用了 `text = '{"key":"value"}'` 而非 `json` **解决方案:** 对于解析后的对象，请使用 `json = '{"key":"value"}'` ### Service 与 Namespace 混淆 **问题:** 无法创建 Durable Object 实例 **原因:** 为 Durable Object 使用了 `service = "room-service"` **解决方案:** 对于 DO 绑定，请使用 `durableObjectNamespace = "Room"` ### 模块名称不匹配 **问题:** 导入失败 **原因:** 模块名称包含路径: `name = "src/index.js"` **解决方案:** 使用简单名称: `name = "index.js"`，并使用路径进行 embed ## 网络访问 **问题:** Fetch 请求因网络错误失败 **原因:** 未配置网络服务 (workerd 没有全局 fetch) **解决方案:** 添加网络服务绑定: capnp services = [(name = "internet", network = (allow = ["public"]))] bindings = [(name = "NET", service = "internet")] 或外部服务: capnp bindings = [(name = "API", service = (external = (address = "api.com:443", http = (style = tls))))] ### "Worker not responding" **原因:** 套接字配置错误、缺少 fetch 处理程序或端口不可用 **解决方案:** 验证套接字 `address` 是否匹配，Worker 是否导出了 `fetch()`，以及端口是否可用 ### "Binding not found" **原因:** 名称不匹配或服务不存在 **解决方案:** 检查配置中的绑定名称是否与代码匹配 (ES 模块使用 `env.BINDING`) ### "Module not found" **原因:** 模块名称与导入不匹配或 embed 路径错误 **解决方案:** 模块 `name` 必须与导入路径完全一致，验证 `embed` 路径 ### "Compatibility error" **原因:** 未设置日期或 API 在该日期不可用 **解决方案:** 设置 `compatibilityDate`，验证 API 在该日期是否可用 ## 性能问题 **问题:** 内存占用过高 **原因:** 缓存过大或隔离区 (isolates) 过多 **解决方案:** 设置缓存限制，减少隔离区数量，或使用 V8 标志 (需谨慎) **问题:** 启动缓慢 **原因:** 模块过多或配置复杂 **解决方案:** 编译为二进制文件 (`workerd compile`)，减少导入 **问题:** 请求超时 **原因:** 外部服务问题或 DNS 问题 **解决方案:** 检查连接性、DNS 解析、TLS 握手