Cloudflare Workers 部署后返回 500 错误，首选通过 Wrangler CLI 运行 wrangler tail 实时查看日志，或在 Cloudflare Dashboard 的 Observability 面板查询历史请求。适用场景为脚本抛出未捕获异常，风险边界在于免费套餐日志保留时长较短且可能存在采样。
先说结论：优先使用命令行实时追踪错误堆栈，Dashboard 适合查询已落地的历史请求日志。
- 先确认：检查本地 Wrangler 版本是否支持 tail 命令且已登录账号
- 先处理：通过
wrangler tail复现请求并捕获控制台输出 - 再验证：在 Dashboard 观测面板确认错误状态码和异常信息已记录
命令速用版
在本地终端执行以下命令即可流式接收 Worker 日志，无需重新部署：
wrangler tail <worker-name>若需过滤特定环境，可添加 `--env` 参数，例如 wrangler tail `--env` production。
为什么会这样
500 错误通常由代码抛出未捕获异常导致，日志记录标准输出和错误堆栈。
Cloudflare Workers 运行时遇到未处理的 Promise 拒绝或同步错误时，会中断请求并返回 500 状态码。系统默认会捕获这些异常信息写入日志流，但需要主动开启查看通道。
分步处理
步骤 1：使用 CLI 实时调试
确保已安装 wrangler 并完成 wrangler login。运行 tail 命令后，在另一个终端或浏览器触发请求，观察本地终端输出的错误堆栈。
步骤 2：通过 Dashboard 查看历史
登录 Cloudflare Dashboard，进入 Workers & Pages，选择对应 Worker，点击左侧 Observability 菜单下的 Logs。使用过滤器筛选 Status code 为 500 的请求。
步骤 3：检查代码逻辑
根据日志中的 Error Message 定位代码行数，重点检查异步函数是否缺少 await 或 try-catch 块。
怎么验证是否生效
触发一次已知会报错的请求，观察 wrangler tail 输出是否包含 Exception 信息，同时刷新 Dashboard Logs 页面确认新条目出现。
若日志为空，检查 Worker 设置中是否禁用了 Logging 功能或权限不足。
常见坑
- 权限不足：子账号可能没有查看 Logs 的权限，需要管理员开启 Observability 访问权
- 采样限制：免费套餐在高流量下可能不会记录所有请求的日志，排查时建议降低流量或使用 CLI
- 环境变量：本地调试与线上环境不一致可能导致本地无错线上 500，需指定
`--env`匹配
常见问题
免费套餐能看到 500 错误日志吗？
可以，免费套餐支持查看基础日志，但保留时长和采样率受限，高并发下可能丢失部分记录。
wrangler tail 需要重新部署吗？
不需要，该命令直接连接线上运行时流式传输日志，不影响当前部署版本。
Dashboard 日志有延迟吗？
通常有几分钟延迟，实时性不如 wrangler tail 命令，适合事后审计而非即时调试。
参考来源
- Cloudflare 官方文档 - Workers Observability Logs: https://developers.cloudflare.com/workers/observability/logs/
- Cloudflare 官方文档 - Wrangler CLI Commands: https://developers.cloudflare.com/workers/wrangler/commands/