sentry-svelte-sdk

Sentry Svelte SDK

面向 Svelte 和 SvelteKit 的定制化向导，可扫描项目并引导你完成 Sentry 设置。

在以下情况下调用此技能

• 用户要求在 Svelte/SvelteKit 应用中“添加 Sentry”或“设置 Sentry”
• 用户希望在 Svelte 或 SvelteKit 中实现错误监控、追踪、会话回放或日志记录
• 用户提到 @sentry/svelte、@sentry/sveltekit 或 Svelte 的 Sentry SDK

**注意：**以下 SDK 版本和 API 反映了撰写时最新的 Sentry 文档（@sentry/sveltekit ≥10.8.0，SvelteKit ≥2.31.0）。 实施前，请务必对照文档进行核实。

---

阶段 1：检测

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

# Detect framework type
cat package.json | grep -E '"svelte"|"@sveltejs/kit"|"@sentry/svelte"|"@sentry/sveltekit"'

# Check for SvelteKit indicators
ls svelte.config.js svelte.config.ts vite.config.ts vite.config.js 2>/dev/null

# Check SvelteKit version (determines which setup pattern to use)
cat package.json | grep '"@sveltejs/kit"'

# Check if Sentry is already installed
cat package.json | grep '"@sentry/'

# Check existing hook files
ls src/hooks.client.ts src/hooks.client.js src/hooks.server.ts src/hooks.server.js \
   src/instrumentation.server.ts 2>/dev/null

# Detect logging libraries (Node side)
cat package.json | grep -E '"pino"|"winston"|"consola"'

# Detect if there's a backend (Go, Python, Ruby, etc.) in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

需要确定的事项：

问题	影响
package.json 中是否有 @sveltejs/kit？	决定使用 SvelteKit 方案还是纯 Svelte 方案
SvelteKit 是否为 ≥2.31.0？	决定使用现代（instrumentation.server.ts）还是旧版设置
是否已有 @sentry/sveltekit？	跳过安装，直接进行功能配置
是否存在 vite.config.ts？	是否可通过 Vite 插件上传源映射
是否找到后端目录？	触发阶段 4 的跨链接建议

---

阶段 2：建议

根据发现的情况提出具体建议。不要提出开放式问题，而是先给出方案：

建议（核心覆盖）：

• ✅ 错误监控 — 始终启用；自动捕获客户端和服务端未处理的错误
• ✅ 追踪 — SvelteKit 同时支持客户端导航跨度和服务端请求跨度；始终建议启用
• ✅ 会话回放 — 面向用户的 SvelteKit 应用建议启用（仅限客户端）

可选（增强可观测性）：

• ⚡ 日志记录 — 通过 Sentry.logger.* 记录结构化日志；当应用使用服务端日志记录或需要日志与追踪关联时建议启用

建议逻辑：

功能	建议启用的情况
错误监控	始终启用 — 不可妥协的基础配置
追踪	SvelteKit 始终启用（客户端 + 服务端）；纯 Svelte 在调用 API 时启用
会话回放	存在面向用户的应用、登录流程或结账页面
日志记录	应用已使用服务端日志记录，或需要搜索结构化日志

建议这样说：“我建议设置错误监控 + 追踪 + 会话回放。要我也添加结构化日志记录吗？”

---

阶段 3：引导设置

确定设置方案

你的项目	软件包	设置复杂度
SvelteKit（≥2.31.0）	@sentry/sveltekit	创建或修改 5 个文件
SvelteKit（<2.31.0）	@sentry/sveltekit	3 个文件（在 hooks.server.ts 中初始化）
纯 Svelte（无 @sveltejs/kit）	@sentry/svelte	单个入口点

---

方案 A：SvelteKit（推荐 — 现代方案，≥2.31.0）

选项 1：向导（推荐）

npx @sentry/wizard@latest -i sveltekit

向导会以交互方式引导你登录、选择组织/项目并设置身份验证令牌，无需手动创建令牌。随后它会安装 SDK、创建所有必需文件（客户端/服务端钩子、Vite 插件配置）、配置源映射上传，并添加 /sentry-example-page 以供验证。运行后跳转到验证。

选项 2：手动设置

步骤 1 — 安装

npm install @sentry/sveltekit --save

步骤 2 — svelte.config.js — 启用插桩

import adapter from "@sveltejs/adapter-auto";

const config = {
  kit: {
    adapter: adapter(),
    experimental: {
      instrumentation: { server: true },
      tracing: { server: true },
    },
  },
};

export default config;

步骤 3 — src/instrumentation.server.ts — 服务端初始化（启动时运行一次）

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT,
  release: process.env.SENTRY_RELEASE,

  sendDefaultPii: true,
  tracesSampleRate: 1.0,    // lower to 0.1–0.2 in production
  enableLogs: true,
});

步骤 4 — src/hooks.client.ts — 客户端初始化

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

Sentry.init({
  dsn: import.meta.env.PUBLIC_SENTRY_DSN ?? import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,

  sendDefaultPii: true,
  tracesSampleRate: 1.0,

  integrations: [
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
    }),
  ],

  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  enableLogs: true,
});

export const handleError = Sentry.handleErrorWithSentry();

步骤 5 — src/hooks.server.ts — 服务端钩子（现代设置中不在此处初始化）

import * as Sentry from "@sentry/sveltekit";
import { sequence } from "@sveltejs/kit/hooks";

export const handleError = Sentry.handleErrorWithSentry();

// sentryHandle() instruments incoming requests and creates root spans
export const handle = Sentry.sentryHandle();

// If you have other handle functions, compose with sequence():
// export const handle = sequence(Sentry.sentryHandle(), myAuthHandle);

步骤 6 — vite.config.ts — 源映射（需要 SENTRY_AUTH_TOKEN）

import { sveltekit } from "@sveltejs/kit/vite";
import { sentrySvelteKit } from "@sentry/sveltekit";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    // sentrySvelteKit MUST come before sveltekit()
    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

---

路径 B：SvelteKit 旧版（低于 2.31.0，或 @sentry/sveltekit 低于 10.8.0）

跳过 instrumentation.server.ts 和 svelte.config.js 的更改。改为直接在 hooks.server.ts 中放置 Sentry.init()：

// src/hooks.server.ts (legacy — init goes here)
import * as Sentry from "@sentry/sveltekit";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

export const handleError = Sentry.handleErrorWithSentry();
export const handle = Sentry.sentryHandle();

hooks.client.ts 和 vite.config.ts 与现代路径完全相同。

---

路径 C：纯 Svelte（无 SvelteKit）

安装：

npm install @sentry/svelte --save

在入口点配置（src/main.ts 或 src/main.js），并确保在挂载应用之前：

import * as Sentry from "@sentry/svelte";
import App from "./App.svelte";

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.MODE,

  sendDefaultPii: true,

  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,
});

const app = new App({ target: document.getElementById("app")! });
export default app;

可选：Svelte 组件跟踪（自动将跟踪注入所有组件）：

// svelte.config.js
import { withSentryConfig } from "@sentry/svelte";

export default withSentryConfig(
  { compilerOptions: {} },
  { componentTracking: { trackComponents: true } }
);

---

针对每项已商定的功能

每次逐一处理一项功能。加载参考文件，按步骤操作，然后验证，再继续下一项：

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终加载（基线）
跟踪	${SKILL_ROOT}/references/tracing.md	需要 API 调用／分布式跟踪
会话回放	${SKILL_ROOT}/references/session-replay.md	面向用户的应用
日志记录	${SKILL_ROOT}/references/logging.md	需要结构化日志／日志与跟踪的关联

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其是否正常工作。

---

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() 插件	✅ 建议	✅ 建议
.env	SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT	✅ 用于源映射	✅ 用于源映射

---

配置参考

Sentry.init() 的关键选项

选项	类型	默认值	说明
dsn	string	—	必需。 使用环境变量；值为空时 SDK 将被禁用
environment	string	"production"	例如："staging"、"development"
release	string	—	例如："[email protected]" 或 git SHA
sendDefaultPii	boolean	false	包含 IP 地址和请求标头
tracesSampleRate	number	—	0–1；开发环境使用 1.0，生产环境使用 0.1–0.2
tracesSampler	function	—	按事务采样；优先于 tracesSampleRate
tracePropagationTargets	(string|RegExp)[]	—	接收分布式跟踪标头的 URL
replaysSessionSampleRate	number	—	录制的所有会话占比（仅客户端）
replaysOnErrorSampleRate	number	—	录制的错误会话占比（仅客户端）
enableLogs	boolean	false	启用 Sentry.logger.* API
beforeSendLog	function	—	发送前筛选／修改日志
debug	boolean	false	在控制台输出详细的 SDK 信息

仅服务端选项（instrumentation.server.ts / hooks.server.ts）

选项	类型	说明
serverName	string	服务端事件上的主机名标签
includeLocalVariables	boolean	将局部变量附加到堆栈帧
shutdownTimeout	number	进程退出前刷新事件所需的毫秒数（默认值：2000）

适配器兼容性

适配器	支持情况
@sveltejs/adapter-auto / adapter-vercel（Node）	✅ 完全支持
@sveltejs/adapter-node	✅ 完全支持
@sveltejs/adapter-cloudflare	⚠️ 部分支持——需要额外设置
Vercel Edge Runtime	❌ 不支持

---

验证

完成设置后，触发测试事件以确认 Sentry 正在接收数据：

<script>
  import * as Sentry from "@sentry/sveltekit";
</script>

<button onclick={() => { throw new Error("Sentry client test"); }}>
  Test Client Error
</button>

<button onclick={() => Sentry.captureMessage("Sentry test message", "info")}>
  Test Message
</button>

// src/routes/sentry-test/+server.ts
export const GET = () => {
  throw new Error("Sentry server test");
};

检查 Sentry 控制面板：

• Issues → 两个错误都应在几秒内出现
• Traces → 查找基于路由的事务
• Replays → 与页面交互后，应能看到会话录制
• Logs → 结构化日志条目（如果已启用日志记录）

如果没有任何内容显示，请在 Sentry.init() 中设置 debug: true，并检查浏览器／服务器控制台中的 SDK 输出。

---

第 4 阶段：交叉关联

完成 Svelte/SvelteKit 设置后，检查是否存在尚未接入 Sentry 的配套后端：

# Look for backend in adjacent directories
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 的后端，请建议使用相应的技能：

检测到的后端	建议的技能
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/

---

故障排查

问题	解决方案
未显示事件	设置 debug: true，检查 DSN，并打开浏览器控制台查看 SDK 错误
Source map 无效	运行 npm run build（而非 dev），确认已设置 SENTRY_AUTH_TOKEN
未捕获服务器错误	确认已从 hooks.server.ts 导出 handleErrorWithSentry()
未捕获客户端错误	确认已从 hooks.client.ts 导出 handleErrorWithSentry()
未录制会话回放	确认 replayIntegration() 仅位于客户端初始化中（绝不要放在服务器端）
sentryHandle() 与其他 handle 无法组合	使用 sequence(Sentry.sentryHandle(), myHandle) 包装
广告拦截器阻止事件	设置 tunnel: "/sentry-tunnel"，并添加服务器端中继端点
SvelteKit 检测未激活	确认 svelte.config.js 中已设置 experimental.instrumentation.server: true
Cloudflare 适配器问题	参阅 docs.sentry.io/platforms/javascript/guides/sveltekit/ 中适配器相关说明
wrapLoadWithSentry / wrapServerLoadWithSentry 报错	这些是旧版包装器——请移除；在 ≥10.8.0 中，sentryHandle() 会自动检测 load 函数