📝本文首发于 栏轩·阁
欢迎访问阅读原文，获取更好的阅读体验。
什么是 Workers Logs
Workers Logs 是 Cloudflare 为 Workers 提供的内置日志服务。你在代码里写console.log，输出会自动采集到 Cloudflare 仪表盘，无需额外配置日志服务器。
支持console.log、console.warn、console.error，用法和浏览器/Node.js 完全一致。
免费额度
| 套餐 | 每日额度 | 保留时长 |
|---|---|---|
| Free | 20 万条/天 | 3 天 |
| Paid | 2000 万条/月 + $0.6/百万条 | 7 天 |
个人项目完全够用。
开启方式
在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 接口可以在需要时用于程序化查询日志
