别再靠猜了：给 Cloudflare Worker 加上日志，问题一眼就知道

📝本文首发于 栏轩·阁

欢迎访问阅读原文，获取更好的阅读体验。

什么是 Workers Logs

Workers Logs 是 Cloudflare 为 Workers 提供的内置日志服务。你在代码里写console.log，输出会自动采集到 Cloudflare 仪表盘，无需额外配置日志服务器。

支持console.log、console.warn、console.error，用法和浏览器/Node.js 完全一致。

免费额度

个人项目完全够用。

开启方式

在wrangler.json中添加 observability 配置：

{"observability":{"enabled":true,"head_sampling_rate":1}}

• enabled: 开启日志采集
• head_sampling_rate: 采样率，1 表示 100% 请求都记录，0.1 表示只记录 10%

部署后日志自动生效。

查看日志

有两种方式：

1. Cloudflare 仪表盘

登录 dash.cloudflare.com → Workers & Pages → 选择你的 Worker →Logs标签。

在这里可以看到所有console.log输出的消息和结构化字段。

2. 命令行实时查看

npx wranglertail

只查看错误：

npx wranglertail--statuserror

适合开发调试时实时观察日志输出。

日志格式建议

基本写法

console.log("用户登录成功",{userId:123,role:"admin"});console.warn("API 返回空数据",{url:"https://api.xxx.com/data",status:200});console.error("数据库查询失败",{error:"Connection timeout"});

推荐规则

• 第一个参数用字符串写描述，让人一眼看懂
• 第二个参数传 JSON 对象，Dashboard 会自动提取为结构化字段，支持筛选和排序
• JSON 键名用英文，方便 Dashboard 识别
• console.log记正常流程，console.warn记预期内的异常，console.error记真正的错误

在哪些位置打日志

• 外部 API 调用：请求 URL、返回状态码、数据条数
• 缓存操作：命中/未命中
• 错误处理：catch 块中记异常信息和上下文
• 请求入口/出口：请求参数、处理结果

避免记录的内容

• API Token、密钥等敏感信息
• 用户密码、邮箱等个人数据
• 大块完整数据（记录条数或摘要即可）

常见问题

日志怎么删除？

Workers Logs不支持主动删除。免费计划保留 3 天，3 天后自动过期。

日志量太大怎么办？

调低采样率：

{"observability":{"enabled":true,"head_sampling_rate":0.1}}

这样只记录 10% 的请求。

日志能导出吗？

付费计划支持 Logpush（推送到 R2、S3、Datadog 等）和 OTel Export（导出到 Sentry、Honeycomb 等 APM 平台）。

常用 API

Workers Logs 提供三个 API 接口，可用于程序化查询日志，适合自动化巡检或集成到自己的后台。

Base URL：

https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/observability/telemetry

认证方式：Authorization: Bearer <API Token>，需要workers_observability:read权限。

查询日志

POST /query

查询 Workers 日志数据，支持按字段筛选和时间范围过滤。返回console.log输出的消息和结构化字段。

示例请求体：

{"limit":20,"filters":[{"key":"module","type":"eq","value":"platform"}]}

查看可查询的字段

POST /keys

返回所有可用的日志字段名，方便你构建筛选条件。

查看字段的取值

POST /values

查看某个字段有哪些可能的取值，比如查看module字段有哪些模块名。

实际应用场景

• 定时查询最近 N 分钟的console.error日志，发现异常自动告警
• 统计某个外部 API 的调用失败率
• 在自己的管理后台嵌入日志面板，替代 Cloudflare 仪表盘
• 分析各模块的调用频率和错误分布

总结

Workers Logs 是 Cloudflare Workers 最实用的功能之一，配置简单（加一行配置就行），免费额度对于个人项目完全够用。核心要点：

• 在代码中加console.log，日志自动采集到 Dashboard
• 推荐用console.log("中文描述", { key: "value" })的格式，兼顾可读性和结构化筛选
• 遇到接口异常时，日志能帮你快速定位问题原因，不用再手动 curl 猜
• 三个 API 接口可以在需要时用于程序化查询日志