在 Cloudflare Workers/Pages…

当需要为 Cloudflare Workers、Pages、Durable Objects、Queues、Workflows 或 Hono 应用配置 Sentry SDK 时，按检测→推荐→配置→验证的流程完成完整接入。

适用场景

解决思路

1. Phase 1 检测：运行命令扫描项目，确认是 Workers 还是 Pages（决定用 withSentry 还是 sentryPagesPlugin）、是否已安装 @sentry/cloudflare、是否使用 Hono、是否配置 Durable Objects、D1、Queues、Workflows、Cron 触发器、compatibility_flags、AI/LLM 库、日志库以及是否有配套前端。
2. Phase 2 推荐：默认推荐 Error Monitoring + Tracing（必选基线），按检测结果可选推荐 Logging、Crons、D1 Instrumentation、Durable Objects、Workflows、AI Monitoring、Metrics，并以具体提案形式给出而非开放式提问。
3. Phase 3 前置条件：在 wrangler.toml 或 wrangler.jsonc 的 compatibility_flags 中添加 nodejs_als（更轻量）或 nodejs_compat，SDK 需要 AsyncLocalStorage。
4. Phase 3 安装：运行 npm install @sentry/cloudflare。
5. Workers 配置：用 Sentry.withSentry((env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0, enableLogs: true, dataCollection: {...} }), { async fetch(request, env, ctx) {...} } satisfies ExportedHandler<Env>) 包裹导出的 handler，会自动插桩 fetch、scheduled、queue、email、tail。
6. Pages 配置：在 functions/_middleware.ts 中使用 Sentry.sentryPagesPlugin((context) => ({ dsn: context.env.SENTRY_DSN, tracesSampleRate: 1.0, enableLogs: true, dataCollection: {...} }))；多个中间件时 Sentry 必须放在数组第一位。
7. SvelteKit 等框架在 Pages 上：使用 Sentry.wrapRequestHandler({ options: {...}, request: event.request, context: event.platform.ctx }, () => resolve(event))。
8. Hono on Workers（推荐 v10.55.0+）：安装 @sentry/hono 与 @sentry/cloudflare，使用 import { sentry } from "@sentry/hono/cloudflare"，并尽早调用 app.use(sentry(app, (env) => ({ dsn: env.SENTRY_DSN, tracesSampleRate: 1.0 })))。
9. Hono 旧方式（已弃用）：仍可用 Sentry.withSentry 包裹 Hono app，但 honoIntegration 已弃用。
10. 配置 SENTRY_DSN 密钥：本地写入 .dev.vars，生产用 npx wrangler secret put SENTRY_DSN，并在 Env 类型中声明 SENTRY_DSN: string。
11. Source Maps：安装 @sentry/vite-plugin 作为 devDependency，在 vite.config.ts 中设置 build.sourcemap: true 并加入 sentryVitePlugin({ org, project, authToken: process.env.SENTRY_AUTH_TOKEN })；也可运行 npx @sentry/wizard@latest -i sourcemaps（需交互式登录，仅配置 source map 上传，不配置 SDK 初始化）。
12. 自动 Release 检测：在 wrangler.toml 添加 [version_metadata] binding = "CF_VERSION_METADATA"；release 优先级为 init 选项 > SENTRY_RELEASE 环境变量 > CF_VERSION_METADATA.id。
13. 按功能加载参考文件：Error Monitoring 用 references/error-monitoring.md，Tracing 用 references/tracing.md，Logging 用 references/logging.md，Crons 用 references/crons.md，Durable Objects 用 references/durable-objects.md；每个功能读完参考文件后严格按步骤执行并验证。
14. 配置选项参考：dsn、tracesSampleRate（0–1，开发用 1.0，生产建议降低）、tracesSampler（与 tracesSampleRate 互斥）、dataCollection（省略时回退到 sendDefaultPii 默认 false；传对象即使为空也会启用宽松默认）、sendDefaultPii、enableLogs、environment、release、debug、tunnel、beforeSend、beforeSendTransaction、beforeSendLog、tracePropagationTargets、skipOpenTelemetrySetup、instrumentPrototypeMethods。
15. SDK 会自动从 env 读取：SENTRY_DSN、SENTRY_RELEASE、SENTRY_ENVIRONMENT、SENTRY_TRACES_SAMPLE_RATE、SENTRY_DEBUG、SENTRY_TUNNEL、CF_VERSION_METADATA。
16. 默认集成包括：dedupeIntegration、inboundFiltersIntegration、functionToStringIntegration、linkedErrorsIntegration、fetchIntegration、honoIntegration（v10.55.0 起弃用）、requestDataIntegration、consoleIntegration。
17. 验证：临时在 fetch handler 中 throw new Error("Sentry test error — delete me")，部署并触发路由，约 30 秒后在 Sentry Issues 面板确认；检查错误捕获、Tracing 的 HTTP spans、Source maps 可读性、D1 的 db.query spans、Crons 面板。
18. Phase 4 交叉链接：检测配套前端（React/Next.js/Svelte/Vue）与后端（Go/Python/Ruby/Node），建议对应 SDK 技能，通过关联 Sentry 项目实现跨浏览器、Worker、后端的分布式追踪。
19. 故障排查：事件不出现时临时设 debug: true 并用 wrangler secret list 确认 DSN；AsyncLocalStorage 未定义时补 compatibility_flags；堆栈被压缩时配置 @sentry/vite-plugin 或运行 wizard 并确认 CI 中的 SENTRY_AUTH_TOKEN；短请求丢事件时确保用 withSentry/sentryPagesPlugin 包裹（它们用 ctx.waitUntil() 刷新）；Hono 错误未捕获时改用 @sentry/hono/cloudflare；Durable Object 错误缺失时用 Sentry.instrumentDurableObjectWithSentry() 包裹；D1 无 spans 时确认 handler 被 withSentry 包裹且查询的是 env 绑定（v10.57.0+ 自动插桩，instrumentD1WithSentry 已弃用，v10.61.0+ 追踪 prepare、batch、exec、withSession）；Scheduled 未监控时确保 withSentry 包裹整个导出对象；Release 未自动检测时添加 [version_metadata]；Workflows 重复事件时确认使用 instrumentWorkflowWithSentry（SDK 会自动禁用 dedupe）。

适用边界 · 注意事项

• 项目不是 Cloudflare Workers/Pages 环境（如纯 Node.js、浏览器前端），应使用对应的框架 SDK 技能。
• 未配置 nodejs_als 或 nodejs_compat 兼容标志时无法使用该 SDK，需先添加标志。
• 没有 Sentry 账号或 DSN、无法使用 Sentry 云服务或自托管实例时无法完成接入。