Tail Workers 常见陷阱

# Tail Workers 常见陷阱与调试 ## 关键陷阱 ### 1. 未使用 `ctx.waitUntil()` **问题：** 异步工作未完成或 Tail 智能体超时 **原因：** 处理程序立即退出；await 会阻塞处理过程 **解决方案：** typescript // ❌ 错误 - 即发即弃 export default { async tail(events) { fetch(endpoint, { body: JSON.stringify(events) }); } }; // ❌ 错误 - 阻塞式 await export default { async tail(events, env, ctx) { await fetch(endpoint, { body: JSON.stringify(events) }); } }; // ✅ 正确 export default { async tail(events, env, ctx) { ctx.waitUntil( (async () => { await fetch(endpoint, { body: JSON.stringify(events) }); await processMore(); })() ); } }; ### 2. 缺少 `tail()` 处理程序 **问题：** 生产者部署失败 **原因：** `tail_consumers` 中的智能体未导出 `tail()` 处理程序 **解决方案：** 确保 `export default { async tail(events, env, ctx) { ... } }` ### 3. 结果 (Outcome) 与 HTTP 状态码的区别 **问题：** 过滤状态错误 **原因：** `outcome` 是脚本执行状态，而非 HTTP 状态码 typescript // ❌ 错误 if (event.outcome === 500) { /* 永远无法匹配 */ } // ✅ 正确 if (event.outcome === 'exception') { /* 脚本抛出异常 */ } if (event.event?.response?.status === 500) { /* HTTP 500 */ } ### 4. 时间戳单位 **问题：** 日期偏差 1000 倍 **原因：** 时间戳是 epoch 毫秒，而非秒 typescript // ❌ 错误: const date = new Date(event.eventTimestamp * 1000); // ✅ 正确: const date = new Date(event.eventTimestamp); ### 5. 类型名称不匹配 **问题：** 使用了 `TailItem` 类型 **原因：** 旧文档使用 `TailItem`，SDK 已更新为 `TraceItem` typescript import type { TraceItem } from '@cloudflare/workers-types'; export default { async tail(events: TraceItem[], env, ctx) { /* ... */ } }; ### 6. 日志量过大 **问题：** 意外的高额成本 **原因：** 在每个生产者请求上都被调用 **解决方案：** 对事件进行采样 typescript export default { async tail(events, env, ctx) { if (Math.random() > 0.1) return; // 10% 采样 ctx.waitUntil(sendToEndpoint(events)); } }; ### 7. 序列化问题 **问题：** `JSON.stringify()` 失败 **原因：** `log.message` 是包含不可序列化值的 `unknown[]` 类型 **解决方案：** typescript const safePayload = events.map(e => ({ ...e, logs: e.logs.map(log => ({ ...log, message: log.message.map(m => { tr