sentry-cloudflare-sdk

所有技能 > SDK 设置 > Cloudflare SDK

Sentry Cloudflare SDK

一款主见鲜明的向导，可扫描你的 Cloudflare 项目，并指导你为 Workers、Pages、Durable Objects、Queues、Workflows 和 Hono 完整设置 Sentry。

在以下情况下调用此技能

• 用户要求“将 Sentry 添加到 Cloudflare Workers”或在 Cloudflare 项目中“设置 Sentry”
• 用户想要安装或配置 @sentry/cloudflare
• 用户想要为 Cloudflare Workers 或 Pages 配置错误监控、追踪、日志记录、定时任务或 AI 监控
• 用户询问 withSentry、sentryPagesPlugin、instrumentDurableObjectWithSentry 或 instrumentD1WithSentry
• 用户想要监控 Cloudflare 上的 Durable Objects、Queues、Workflows、定时处理程序或邮件处理程序

**注意：**以下 SDK 版本和 API 反映了撰写本文时 Sentry 文档中的最新内容（@sentry/cloudflare v10.61.0）。 实施前，请务必对照docs.sentry.io/platforms/javascript/guides/cloudflare/进行核实。

---

第 1 阶段：检测

在提出任何建议之前，先运行以下命令了解项目：

# Detect Cloudflare project
ls wrangler.toml wrangler.jsonc wrangler.json 2>/dev/null

# Detect existing Sentry
cat package.json 2>/dev/null | grep -E '"@sentry/'

# Detect project type (Workers vs Pages)
ls functions/ functions/_middleware.js functions/_middleware.ts 2>/dev/null && echo "Pages detected"
cat wrangler.toml 2>/dev/null | grep -E 'main|pages_build_output_dir'

# Detect framework
cat package.json 2>/dev/null | grep -E '"hono"|"remix"|"astro"|"svelte"'

# Detect Durable Objects
cat wrangler.toml 2>/dev/null | grep -i 'durable_objects'

# Detect D1 databases
cat wrangler.toml 2>/dev/null | grep -i 'd1_databases'

# Detect Queues
cat wrangler.toml 2>/dev/null | grep -i 'queues'

# Detect Workflows
cat wrangler.toml 2>/dev/null | grep -i 'workflows'

# Detect Scheduled handlers (cron triggers)
cat wrangler.toml 2>/dev/null | grep -i 'crons\|triggers'

# Detect compatibility flags
cat wrangler.toml 2>/dev/null | grep -i 'compatibility_flags'
cat wrangler.jsonc 2>/dev/null | grep -i 'compatibility_flags'

# Detect AI/LLM libraries
cat package.json 2>/dev/null | grep -E '"openai"|"@anthropic-ai"|"ai"|"@google/generative-ai"|"@langchain"'

# Detect logging libraries
cat package.json 2>/dev/null | grep -E '"pino"|"winston"'

# Check for companion frontend
ls frontend/ web/ client/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

需要确定的事项：

问题	影响
Workers 还是 Pages？	决定使用哪种包装器：withSentry 还是 sentryPagesPlugin
是否使用 Hono 框架？	建议使用独立的 @sentry/hono 包（v10.55.0+），实现更简洁的集成
是否已安装 @sentry/cloudflare？	跳过安装，进入功能配置
是否配置了 Durable Objects？	建议使用 instrumentDurableObjectWithSentry
是否绑定了 D1 数据库？	withSentry 会自动为 D1 绑定插桩（v10.57.0+）；无需手动包装
是否配置了 Queues？	withSentry 会自动为队列处理程序插桩
是否配置了 Workflows？	建议使用 instrumentWorkflowWithSentry
是否配置了 Cron 触发器？	withSentry 会自动为定时处理程序插桩；建议启用 Crons 监控
是否设置了 nodejs_als 或 nodejs_compat 标志？	必需 — SDK 需要 AsyncLocalStorage
是否使用 AI/LLM 库？	建议使用 AI 监控集成
是否有配套的前端？	触发第 4 阶段的交叉链接

---

阶段 2：推荐

根据你的发现，提出具体建议。不要提出开放式问题——直接给出方案：

推荐（核心覆盖）：

• ✅ 错误监控 — 始终启用；捕获 fetch、scheduled、queue、email 和 Durable Object 处理程序中未处理的异常
• ✅ 追踪 — 自动生成 HTTP 请求 span、出站 fetch 追踪和 D1 查询 span

可选（增强可观测性）：

• ⚡ 日志记录 — 通过 Sentry.logger.* 记录结构化日志；需要搜索日志时建议启用
• ⚡ 定时任务 — 检测遗漏或失败的定时任务；配置了 cron 触发器时建议启用
• ⚡ D1 插桩 — 自动生成查询 span 和面包屑；绑定了 D1 时建议启用
• ⚡ Durable Objects — 自动捕获错误并为 DO 方法生成 span；配置了 DO 时建议启用
• ⚡ 工作流 — 自动为工作流步骤创建 span；配置了 Workflows 时建议启用
• ⚡ AI 监控 — Vercel AI SDK、OpenAI、Anthropic、LangChain；检测到 AI 库时建议启用

推荐逻辑：

功能	推荐条件……
错误监控	始终 — 不可妥协的基础配置
追踪	始终 — HTTP 请求追踪和出站 fetch 价值很高
日志记录	应用需要结构化日志搜索或日志与追踪的关联
定时任务	在 wrangler.toml 中配置了 cron 触发器
D1 插桩	存在 D1 数据库绑定
Durable Objects	已配置 Durable Object 绑定
工作流	已配置工作流绑定
AI 监控	应用使用 Vercel AI SDK、OpenAI、Anthropic 或 LangChain
指标	应用需要自定义计数器、仪表盘或分布

建议：“我建议设置错误监控 + 追踪。要我也添加 D1 插桩和定时任务监控吗？”

---

阶段 3：指导

选项 1：Source Maps 向导

你需要自行运行此向导 — 向导会打开浏览器进行登录，并需要 Agent 无法处理的交互式输入。请复制并粘贴到终端：

npx @sentry/wizard@latest -i sourcemaps

这会设置 source map 上传，让生产环境的堆栈跟踪显示为可读代码。它不会设置 SDK 初始化——你仍需按照下面的选项 2 完成实际的 SDK 设置。

完成后，继续选项 2 进行 SDK 设置。

注意： 与框架 SDK（Next.js、SvelteKit）不同，目前没有针对 Cloudflare 的向导集成。sourcemaps 向导仅处理 source map 上传配置。

---

选项 2：手动设置

前提条件：兼容性标志

SDK 需要 AsyncLocalStorage。请在 Wrangler 配置中添加以下标志之一：

wrangler.toml：

compatibility_flags = ["nodejs_als"]
# or: compatibility_flags = ["nodejs_compat"]

wrangler.jsonc：

{
  "compatibility_flags": ["nodejs_als"]
}

nodejs_als 更轻量——它只启用 AsyncLocalStorage。如果代码还需要其他 Node.js API，请使用 nodejs_compat。

安装

npm install @sentry/cloudflare

Workers 设置

使用 withSentry 封装处理程序。这会自动为 fetch、scheduled、queue、email 和 tail 处理程序添加插桩：

import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
    enableLogs: true,
    dataCollection: {
      // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
      // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection
      // userInfo: false,
      // httpBodies: [],
    },
  }),
  {
    async fetch(request, env, ctx) {
      return new Response("Hello World!");
    },
  } satisfies ExportedHandler<Env>,
);

要点：

• 第一个参数是一个接收 env 的回调——用它读取 SENTRY_DSN 等机密信息
• SDK 会自动从 env 读取 DSN、环境、版本、调试、隧道和追踪采样率（参见环境变量）
• withSentry 会封装所有导出的处理程序——你无需单独封装 scheduled、queue 等处理程序

Pages 设置

将 sentryPagesPlugin 用作中间件：

// functions/_middleware.ts
import * as Sentry from "@sentry/cloudflare";

export const onRequest = Sentry.sentryPagesPlugin((context) => ({
  dsn: context.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
}));

串联多个中间件：

import * as Sentry from "@sentry/cloudflare";

export const onRequest = [
  // Sentry must be first
  Sentry.sentryPagesPlugin((context) => ({
    dsn: context.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  })),
  // Add more middlewares here
];

直接使用 wrapRequestHandler（适用于 Cloudflare Pages 上的 SvelteKit 等框架）：

import * as Sentry from "@sentry/cloudflare";

export const handle = ({ event, resolve }) => {
  return Sentry.wrapRequestHandler(
    {
      options: {
        dsn: event.platform.env.SENTRY_DSN,
        tracesSampleRate: 1.0,
      },
      request: event.request,
      context: event.platform.ctx,
    },
    () => resolve(event),
  );
};

Cloudflare Workers 上的 Hono

推荐（v10.55.0+）： Hono 应用请使用独立的 @sentry/hono 包：

npm install @sentry/hono @sentry/cloudflare

@sentry/cloudflare 包是一个对等依赖，必须与 @sentry/hono 保持同步。

import { Hono } from "hono";
import { sentry } from "@sentry/hono/cloudflare";

type Bindings = { SENTRY_DSN: string };

const app = new Hono<{ Bindings: Bindings }>();

// Initialize Sentry middleware as early as possible
app.use(
  sentry(app, (env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  })),
);

app.get("/", (ctx) => ctx.json({ message: "Hello" }));

app.get("/error", () => {
  throw new Error("Test error");
});

export default app;

sentry() 中间件会自动捕获错误，并根据路由模式创建事务 Span。

旧版方案（已弃用）： 仍可通过 withSentry 使用 @sentry/cloudflare，但 honoIntegration 已弃用：

import { Hono } from "hono";
import * as Sentry from "@sentry/cloudflare";

const app = new Hono();

app.get("/", (ctx) => ctx.json({ message: "Hello" }));

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  }),
  app,
);

设置 SENTRY_DSN 密钥

将 DSN 保存为 Cloudflare 密钥，不要将其硬编码：

# Local development: add to .dev.vars
echo 'SENTRY_DSN="https://[email protected]/0"' >> .dev.vars

# Production: set as a secret
npx wrangler secret put SENTRY_DSN

将绑定添加到 Env 类型：

interface Env {
  SENTRY_DSN: string;
  // ... other bindings
}

Source Map 设置

Source Map 能让生产环境中的堆栈跟踪易于阅读。大多数 Cloudflare 项目都通过 Wrangler 使用 Vite 构建——配置 Sentry Vite 插件，以便在构建时上传 Source Map：

npm install @sentry/vite-plugin --save-dev

import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: {
    sourcemap: true,
  },
  plugins: [
    sentryVitePlugin({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

SENTRY_AUTH_TOKEN 是构建时密钥。有关创建令牌并将其配置到 CI 中的信息，请参阅 sentry-source-maps。上文提到的 npx @sentry/wizard@latest -i sourcemaps 快捷命令会自动完成此设置。

---

自动检测版本

SDK 可以通过 Cloudflare 的版本元数据绑定自动检测版本：

wrangler.toml：

[version_metadata]
binding = "CF_VERSION_METADATA"

版本优先级（从高到低）：

1. 传递给 Sentry.init() 的 release 选项
2. SENTRY_RELEASE 环境变量
3. CF_VERSION_METADATA.id 绑定

---

对每项已确定的功能

加载对应的参考文件，并按照其中的步骤操作：

功能	参考文件	加载时机……
错误监控	references/error-monitoring.md	始终加载（基线）——未处理的异常、手动捕获、作用域、信息补充
追踪	references/tracing.md	HTTP 请求追踪、出站 fetch Span、D1 查询 Span、分布式追踪
日志记录	references/logging.md	通过 Sentry.logger.* 记录结构化日志、日志与追踪的关联
Crons	references/crons.md	计划任务处理程序监控、withMonitor、签到 API
Durable Objects	references/durable-objects.md	为 Durable Object 类插桩，以捕获错误和 Span

对于每项功能：阅读参考文件，严格遵循其中的步骤，并在继续之前进行验证。

---

配置参考

Sentry.init() 选项

选项	类型	默认值	说明
dsn	string	—	必填。未设置时自动从 env.SENTRY_DSN 读取
tracesSampleRate	number	—	范围为 0–1；开发环境建议设为 1.0，生产环境建议设得更低
tracesSampler	function	—	动态采样函数；不能与 tracesSampleRate 同时使用
dataCollection	object	除非设置，否则采用保守默认值	控制 SDK 捕获的数据（userInfo、httpBodies 等）。省略时回退到 sendDefaultPii（默认值为 false）；传入此对象（即使是 {}）也会启用宽松默认值。请参阅数据收集参考
sendDefaultPii	boolean	false	旧选项。建议使用 dataCollection 控制捕获的数据
enableLogs	boolean	false	启用 Sentry Logs 产品
environment	string	自动	未设置时从 env.SENTRY_ENVIRONMENT 读取
release	string	自动	从 CF_VERSION_METADATA.id 或 SENTRY_RELEASE 检测
debug	boolean	false	未设置时从 env.SENTRY_DEBUG 读取。将 SDK 活动记录到控制台
tunnel	string	—	未设置时从 env.SENTRY_TUNNEL 读取
beforeSend	function	—	发送前筛选/修改错误事件
beforeSendTransaction	function	—	发送前筛选/修改事务事件
beforeSendLog	function	—	发送前筛选/修改日志条目
tracePropagationTargets	(string|RegExp)[]	所有 URL	控制哪些出站请求会携带跟踪标头
skipOpenTelemetrySetup	boolean	false	选择不使用 OpenTelemetry 兼容跟踪器
instrumentPrototypeMethods	boolean | string[]	false	Durable Object：为原型方法添加检测，以创建 RPC span

数据收集参考

dataCollection: {
  // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
  // https://docs.sentry.io/platforms/javascript/configuration/options/#dataCollection
  // userInfo: false,
  // httpBodies: [],
},

环境变量（从 env 读取）

SDK 会自动从 Cloudflare env 对象读取以下变量：

变量	用途
SENTRY_DSN	Sentry 初始化所用的 DSN
SENTRY_RELEASE	发布版本字符串
SENTRY_ENVIRONMENT	环境名称（production、staging）
SENTRY_TRACES_SAMPLE_RATE	跟踪采样率（解析为浮点数）
SENTRY_DEBUG	启用调试模式（"true" / "1"）
SENTRY_TUNNEL	用于代理事件的 Tunnel URL
CF_VERSION_METADATA	Cloudflare 版本元数据绑定（自动检测发布版本）

默认集成

以下集成由 getDefaultIntegrations() 自动注册：

集成	用途
dedupeIntegration	防止重复事件（Workflows 中禁用）
inboundFiltersIntegration	按类型、消息、URL 筛选事件
functionToStringIntegration	保留原始函数名称
linkedErrorsIntegration	沿错误中的 cause 链追踪
fetchIntegration	跟踪出站 fetch() 调用并创建面包屑
honoIntegration	在 v10.55.0 中已弃用 — 请改用 @sentry/hono 包。自动捕获 Hono onError 异常
requestDataIntegration	将请求数据附加到事件
consoleIntegration	将 console.* 调用捕获为面包屑

---

验证

完成设置后，验证 Sentry 是否正常工作：

// Add temporarily to your fetch handler, then remove
export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  }),
  {
    async fetch(request, env, ctx) {
      throw new Error("Sentry test error — delete me");
    },
  } satisfies ExportedHandler<Env>,
);

部署并触发该路由，然后查看你的 Sentry Issues 仪表板 — 错误应会在约 30 秒内出现。

验证清单：

检查项	方法
已捕获错误	在 fetch 处理程序中抛出错误，并在 Sentry 中确认
跟踪正常工作	检查 Performance 选项卡中的 HTTP span
Source map 正常工作	检查堆栈跟踪是否显示易读的文件名/行号
D1 span（如已配置）	运行 D1 查询，检查是否有 db.query span
定时监控（如已配置）	触发 cron，并检查 Crons 仪表板

第 4 阶段：交叉关联

完成 Cloudflare 设置后，检查是否有配套服务：

# Check for companion frontend
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"|"astro"'

# Check for companion backend in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

如果检测到前端，建议使用匹配的 SDK 技能：

检测到的前端	建议的技能
React	sentry-react-sdk
Next.js	sentry-nextjs-sdk
Svelte/SvelteKit	sentry-svelte-sdk
Vue/Nuxt	参见 docs.sentry.io/platforms/javascript/guides/vue/

如果在其他目录中检测到后端：

检测到的后端	建议的技能
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Node.js（Express、Fastify）	sentry-node-sdk

将前端和后端关联到 Sentry 项目后，即可实现分布式追踪，在单个追踪视图中查看贯穿浏览器、Cloudflare Worker 和后端 API 的堆栈跟踪。

---

故障排除

问题	原因	解决方案
未显示事件	未设置 DSN，或 debug: false 隐藏了错误	在初始化选项中临时设置 debug: true；使用 wrangler secret list 验证是否已设置 SENTRY_DSN 密钥
AsyncLocalStorage is not defined	缺少兼容性标志	在 wrangler.toml 的 compatibility_flags 中添加 nodejs_als 或 nodejs_compat
堆栈跟踪显示的是压缩代码	未上传源映射	配置 @sentry/vite-plugin，或运行 npx @sentry/wizard -i sourcemaps；验证 CI 中的 SENTRY_AUTH_TOKEN
短时请求丢失事件	SDK 未在 Worker 终止前刷新	确保处理程序由 withSentry 或 sentryPagesPlugin 包装——它们会使用 ctx.waitUntil() 执行刷新
未捕获 Hono 错误	未对 Hono 应用进行检测	使用 @sentry/hono/cloudflare——导入 sentry 中间件并调用 app.use(sentry(app, options))
缺少 Durable Object 错误	未对 DO 类进行检测	使用 Sentry.instrumentDurableObjectWithSentry() 包装类——参见 references/durable-objects.md
D1 查询未创建跨度	处理程序未使用 withSentry 包装，或查询的不是 env 绑定	env 上的 D1 绑定由 withSentry 自动检测（v10.57.0+），无需手动包装（instrumentD1WithSentry 已弃用）。v10.61.0+ 会追踪所有查询方法（prepare、batch、exec、withSession）
未监控定时处理程序	处理程序未使用 withSentry 包装	确保 export default Sentry.withSentry(...) 包装了整个导出的处理程序对象
未自动检测到发布版本	未配置 CF_VERSION_METADATA 绑定	在 wrangler.toml 中添加 [version_metadata]，并设置 binding = "CF_VERSION_METADATA"
Workflows 中出现重复事件	去重集成过滤了步骤失败事件	SDK 会自动为 Workflows 禁用去重；验证是否使用了 instrumentWorkflowWithSentry