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

什么是 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 wrangler tail

只查看错误：

npx wrangler tail --status error

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

日志格式建议

基本写法

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 接口可以在需要时用于程序化查询日志