sentry-svelte-sdk

所有技能 > SDK 设置 > 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）。 实施前，请务必对照docs.sentry.io/platforms/javascript/guides/sveltekit/进行确认。

---

阶段 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：向导（推荐）

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

npx @sentry/wizard@latest -i sveltekit

它会处理登录、组织/项目选择、SDK 安装、客户端/服务端钩子、Vite 插件配置、源映射上传，并添加 /sentry-example-page。

完成后，请返回并跳转至验证。

如果用户跳过向导，请继续阅读下方的选项 2（手动设置）。

选项 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,

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/sveltekit/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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,

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/sveltekit/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  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,

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

  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，严格按照步骤操作，并验证其是否正常工作。

---

配置参考

Sentry.init() 关键选项

选项	类型	默认值	备注
dsn	string	—	必填。 使用环境变量；值为空时 SDK 将禁用
environment	string	"production"	例如："staging"、"development"
release	string	—	例如："[email protected]" 或 git SHA
dataCollection	object	—	控制收集哪些数据（userInfo、cookies、headers 等）
dataCollection.userInfo	boolean	true	根据插桩数据自动填充 user.* 字段
dataCollection.cookies	boolean|object	true	Cookie 收集与筛选
dataCollection.httpHeaders	object	{request: true, response: true}	收集请求／响应的 HTTP 标头
dataCollection.httpBodies	string[]	["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]	要收集的 HTTP 正文类型
dataCollection.queryParams	boolean|object	true	查询参数收集与筛选
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	❌ 不支持

SvelteKit 文件摘要

文件	用途	Modern	Legacy
src/instrumentation.server.ts	服务端 Sentry.init() — 在启动时运行一次	✅ 必需	❌
src/hooks.client.ts	客户端 Sentry.init() + handleError	✅ 必需	✅ 必需
src/hooks.server.ts	handleError + sentryHandle()（无 init）	✅ 必需	✅ 在此处初始化
svelte.config.js	启用 experimental.instrumentation.server	✅ 必需	❌
vite.config.ts	用于源映射的 sentrySvelteKit() 插件	✅ 建议	✅ 建议
.env	SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT	✅ 用于源映射	✅ 用于源映射

---

验证

完成设置后，触发测试事件，以确认 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 控制面板：

• 问题 → 两个错误都应在几秒内显示
• 追踪 → 查找基于路由的事务
• 重放 → 页面交互后可查看会话录制
• 日志 → 结构化日志条目（如果已启用日志记录）

如果没有显示任何内容，请在 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 错误
源映射不起作用	运行 npm run build（而非 dev），确认已设置 SENTRY_AUTH_TOKEN
未捕获服务端错误	确认已从 hooks.server.ts 导出 handleErrorWithSentry()
未捕获客户端错误	确认已从 hooks.client.ts 导出 handleErrorWithSentry()
未录制会话重放	确认 replayIntegration() 仅用于客户端初始化（切勿用于服务端）
sentryHandle() 与其他句柄无法组合	使用 sequence(Sentry.sentryHandle(), myHandle) 包装
广告拦截器阻止事件	设置 tunnel: "/sentry-tunnel"，并添加服务端中继端点
SvelteKit instrumentation 未激活	确认 svelte.config.js 中的 experimental.instrumentation.server: true
Cloudflare 适配器问题	请参阅 docs.sentry.io/platforms/javascript/guides/sveltekit/ 中针对适配器的说明
wrapLoadWithSentry / wrapServerLoadWithSentry 错误	这些是旧版包装器 — 请移除；在 ≥10.8.0 中，sentryHandle() 会自动为 load 函数添加 instrumentation