在 Svelte 或 SvelteKit 项目中接入…

为 Svelte 或 SvelteKit 应用设置 Sentry 错误监控、性能追踪、会话回放和结构化日志时，按项目类型选择向导或手动配置。

适用场景

解决思路

1. 运行 `cat package.json | grep -E '"svelte"|"@sveltejs/kit"|"@sentry/svelte"|"@sentry/sveltekit"'` 检测框架类型。
2. 运行 `ls svelte.config.js svelte.config.ts vite.config.ts vite.config.js 2>/dev/null` 检查 SvelteKit 指示文件。
3. 运行 `cat package.json | grep '"@sveltejs/kit"'` 检查 SvelteKit 版本，以决定使用现代还是旧版设置模式。
4. 运行 `cat package.json | grep '"@sentry/'` 检查是否已安装 Sentry，若已安装则跳过安装并直接做功能配置。
5. 运行 `ls src/hooks.client.ts src/hooks.client.js src/hooks.server.ts src/hooks.server.js src/instrumentation.server.ts 2>/dev/null` 检查现有 hook 文件。
6. 运行 `cat package.json | grep -E '"pino"|"winston"|"consola"'` 检测 Node 侧日志库。
7. 运行 `ls ../backend ../server ../api 2>/dev/null` 和 `cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3` 检测相邻后端目录。
8. 根据检测结果判断：`@sveltejs/kit` 存在则走 SvelteKit 路径，否则走 plain Svelte 路径；SvelteKit >=2.31.0 走现代路径，否则走旧版路径；已有 `@sentry/sveltekit` 则跳过安装；存在 `vite.config.ts` 则启用 Vite 插件上传 source map；发现后端目录则触发 Phase 4 交叉链接建议。
9. 推荐核心覆盖：Error Monitoring 始终启用；Tracing 对 SvelteKit 始终推荐（客户端导航 span 和服务端请求 span）；Session Replay 对面向用户的 SvelteKit 应用推荐（仅客户端）；Logging 在应用已有服务端日志或需要 log-to-trace 关联时可选。
10. 用提案式话术推荐：『我推荐设置 Error Monitoring + Tracing + Session Replay。需要我再添加结构化 Logging 吗？』，不要问开放式问题。
11. 确定设置路径：SvelteKit >=2.31.0 使用 `@sentry/sveltekit`，需创建/修改 5 个文件；SvelteKit <2.31.0 使用 `@sentry/sveltekit`，在 `hooks.server.ts` 初始化，共 3 个文件；plain Svelte（无 `@sveltejs/kit`）使用 `@sentry/svelte`，单入口点。
12. Path A 现代 SvelteKit 优先使用向导：让用户自己在终端运行 `npx @sentry/wizard@latest -i sveltekit`；该向导处理登录、组织/项目选择、SDK 安装、客户端/服务端 hooks、Vite 插件配置、source map 上传，并添加 `/sentry-example-page`；完成后跳到 Verification。
13. 如果跳过向导，Path A 手动第 1 步：运行 `npm install @sentry/sveltekit --save` 安装。
14. Path A 手动第 2 步：在 `svelte.config.js` 中启用 instrumentation，配置 `adapter`、`experimental.instrumentation.server: true`、`experimental.tracing.server: true`。
15. Path A 手动第 3 步：创建 `src/instrumentation.server.ts` 做服务端初始化，启动时运行一次；调用 `Sentry.init` 设置 `dsn`、`environment`、`release`、`dataCollection`、`tracesSampleRate: 1.0`（生产降到 0.1–0.2）、`enableLogs: true`；如需禁用用户数据和 HTTP body，取消注释 `userInfo: false` 和 `httpBodies: []`。
16. Path A 手动第 4 步：创建 `src/hooks.client.ts` 做客户端初始化；调用 `Sentry.init` 设置 `dsn`（`import.meta.env.PUBLIC_SENTRY_DSN ?? import.meta.env.VITE_SENTRY_DSN`）、`environment`、`dataCollection`、`tracesSampleRate: 1.0`，在 `integrations` 中加入 `Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })`，设置 `replaysSessionSampleRate: 0.1`、`replaysOnErrorSampleRate: 1.0`、`enableLogs: true`，并导出 `handleError = Sentry.handleErrorWithSentry()`。
17. Path A 手动第 5 步：创建 `src/hooks.server.ts`，现代设置中不要在此初始化；导出 `handleError = Sentry.handleErrorWithSentry()`，导出 `handle = Sentry.sentryHandle()` 以 instrument 传入请求并创建 root span；如有其他 handle，使用 `sequence(Sentry.sentryHandle(), myAuthHandle)` 组合。
18. Path A 手动第 6 步：修改 `vite.config.ts` 做 source map；导入 `sentrySvelteKit`，确保 `sentrySvelteKit({ org: process.env.SENTRY_ORG, project: process.env.SENTRY_PROJECT, authToken: process.env.SENTRY_AUTH_TOKEN })` 放在 `sveltekit()` 之前；在 `.env` 添加且不要提交 `SENTRY_AUTH_TOKEN=sntrys_...`、`SENTRY_ORG=my-org-slug`、`SENTRY_PROJECT=my-project-slug`。
19. Path B 旧版 SvelteKit（<2.31.0 或 `@sentry/sveltekit` <10.8.0）：跳过 `instrumentation.server.ts` 和 `svelte.config.js` 修改；在 `src/hooks.server.ts` 中直接 `Sentry.init` 设置 `dsn`、`tracesSampleRate: 1.0`、`enableLogs: true`，并导出 `handleError = Sentry.handleErrorWithSentry()` 和 `handle = Sentry.sentryHandle()`；`hooks.client.ts` 和 `vite.config.ts` 与现代路径相同。
20. Path C plain Svelte 安装：运行 `npm install @sentry/svelte --save`。
21. Path C plain Svelte 配置：在 `src/main.ts` 或 `src/main.js` 中、挂载应用之前调用 `Sentry.init`，设置 `dsn`、`environment`、`dataCollection`，在 `integrations` 中加入 `Sentry.browserTracingIntegration()` 和 `Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })`，设置 `tracesSampleRate: 1.0`、`tracePropagationTargets: ["localhost", /^https:\/\/yourapi\.io/]`、`replaysSessionSampleRate: 0.1`、`replaysOnErrorSampleRate: 1.0`、`enableLogs: true`，然后 `new App({ target: document.getElementById("app")! })`。
22. Path C 可选 Svelte 组件追踪：在 `svelte.config.js` 中使用 `withSentryConfig`，传入 `{ componentTracking: { trackComponents: true } }` 自动为所有组件注入追踪。
23. 对每个已同意功能逐个走查：加载对应参考文件，按步骤执行，再验证后继续；Error Monitoring 读 `${SKILL_ROOT}/references/error-monitoring.md`（始终）；Tracing 读 `${SKILL_ROOT}/references/tracing.md`（需要 API 调用/分布式追踪）；Session Replay 读 `${SKILL_ROOT}/references/session-replay.md`（面向用户应用）；Logging 读 `${SKILL_ROOT}/references/logging.md`（结构化日志/log-to-trace 关联）。
24. 配置 `Sentry.init()` 关键选项时检查：`dsn` 必填且为空时 SDK 禁用；`environment` 默认 `"production"`；`release` 如 `"my-app@1.2.3"` 或 git SHA；`dataCollection` 控制 userInfo、cookies、httpHeaders、httpBodies、queryParams；`tracesSampleRate` 0–1，开发 1.0、生产 0.1–0.2；`tracesSampler` 每事务采样并覆盖 `tracesSampleRate`；`tracePropagationTargets` 指定接收分布式追踪头的 URL；`replaysSessionSampleRate` 所有会话录制比例（仅客户端）；`replaysOnErrorSampleRate` 错误会话录制比例（仅客户端）；`enableLogs` 默认 false，启用 `Sentry.logger.*`；`beforeSendLog` 发送前过滤/修改日志；`debug` 默认 false，输出详细 SDK 日志。
25. 服务端专用选项（`instrumentation.server.ts` / `hooks.server.ts`）：`serverName` 设置服务端事件主机名标签；`includeLocalVariables` 将局部变量附加到堆栈帧；`shutdownTimeout` 进程退出前刷写事件的毫秒数（默认 2000）。
26. 检查适配器兼容性：`@sveltejs/adapter-auto` / adapter-vercel（Node）完全支持；`@sveltejs/adapter-node` 完全支持；`@sveltejs/adapter-cloudflare` 部分支持且需要额外设置；Vercel Edge Runtime 不支持。
27. 按 SvelteKit 文件摘要创建/修改：`src/instrumentation.server.ts` 现代必需，服务端 `Sentry.init()` 启动一次；`src/hooks.client.ts` 现代和旧版都必需，客户端 `Sentry.init()` + `handleError`；`src/hooks.server.ts` 现代导出 `handleError` + `sentryHandle()` 且不初始化，旧版在此初始化；`svelte.config.js` 现代必需，启用 `experimental.instrumentation.server`；`vite.config.ts` 推荐用 `sentrySvelteKit()` 插件做 source map；`.env` 为 source map 设置 `SENTRY_AUTH_TOKEN`、`SENTRY_ORG`、`SENTRY_PROJECT`。
28. 验证客户端：创建 `src/routes/sentry-test/+page.svelte`，导入 `* as Sentry from "@sentry/sveltekit"`，添加按钮 `onclick={() => { throw new Error("Sentry client test"); }}` 和按钮 `onclick={() => Sentry.captureMessage("Sentry test message", "info")}`。
29. 验证服务端：创建 `src/routes/sentry-test/+server.ts`，导出 `GET = () => { throw new Error("Sentry server test"); }`。
30. 检查 Sentry dashboard：Issues 中两个错误应在几秒内出现；Traces 中查找基于路由的 transactions；Replays 中在页面交互后可见会话录制；Logs 中查看结构化日志（若启用 logging）。
31. 如果什么都没出现：在 `Sentry.init()` 中设置 `debug: true`，检查浏览器/服务端控制台中的 SDK 输出。
32. Phase 4 交叉链接：运行 `ls ../backend ../server ../api ../go ../python 2>/dev/null`，`cat ../go.mod 2>/dev/null | head -3`，`cat ../requirements.txt ../pyproject.toml 2>/dev/null | head -3`，`cat ../Gemfile 2>/dev/null | head -3` 检查相邻后端是否缺少 Sentry 覆盖。
33. 如果检测到后端且未配置 Sentry，建议对应技能：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` 并参考 `docs.sentry.io/platforms/javascript/guides/express/`。
34. 排障：事件不出现 -> 设置 `debug: true`、检查 DSN、打开浏览器控制台看 SDK 错误。
35. 排障：source map 不工作 -> 运行 `npm run build`（不是 `dev`），确认 `SENTRY_AUTH_TOKEN` 已设置。
36. 排障：服务端错误未捕获 -> 确保从 `hooks.server.ts` 导出 `handleErrorWithSentry()`。
37. 排障：客户端错误未捕获 -> 确保从 `hooks.client.ts` 导出 `handleErrorWithSentry()`。
38. 排障：Session Replay 未录制 -> 确认 `replayIntegration()` 只在客户端初始化中，绝不在服务端。
39. 排障：`sentryHandle()` 与其他 handle 不组合 -> 用 `sequence(Sentry.sentryHandle(), myHandle)` 包裹。
40. 排障：广告拦截器阻止事件 -> 设置 `tunnel: "/sentry-tunnel"` 并添加服务端中继端点。
41. 排障：SvelteKit instrumentation 未激活 -> 确认 `svelte.config.js` 中 `experimental.instrumentation.server: true`。
42. 排障：Cloudflare adapter 问题 -> 查阅 `docs.sentry.io/platforms/javascript/guides/sveltekit/` 的适配器专用说明。
43. 排障：`wrapLoadWithSentry` / `wrapServerLoadWithSentry` 报错 -> 这些是旧版 wrapper，移除它们；在 >=10.8.0 中 `sentryHandle()` 会自动 instrument load functions。

适用边界 · 注意事项

• 使用 Vercel Edge Runtime 时不适用，该运行时不受支持。
• 使用 `@sveltejs/adapter-cloudflare` 时仅部分支持，需要按 Sentry 文档做额外设置后才能使用。
• 没有 Sentry 账号/项目、DSN 或 `SENTRY_AUTH_TOKEN`（source map 需要）时不适用；需先开通/获取，若无法运行交互式向导则改用手动路径。