sentry-svelte-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sentry Svelte SDK

Opinionated wizard that scans your project and guides you through complete Sentry setup for Svelte and SvelteKit.

这是一个预设配置的向导工具，会扫描你的项目并引导你完成Svelte和SvelteKit的完整Sentry设置流程。

Invoke This Skill When

何时使用本指南

User asks to "add Sentry to Svelte" or "set up Sentry" in a Svelte/SvelteKit app
User wants error monitoring, tracing, session replay, or logging in Svelte or SvelteKit
User mentions
```
@sentry/svelte
```
,
```
@sentry/sveltekit
```
, or Sentry SDK for Svelte

Note: SDK versions and APIs below reflect current Sentry docs at time of writing (
@sentry/sveltekit
≥10.8.0, SvelteKit ≥2.31.0). Always verify against docs.sentry.io/platforms/javascript/guides/sveltekit/ before implementing.

用户要求在Svelte/SvelteKit应用中“添加Sentry”或“设置Sentry”
用户需要为Svelte或SvelteKit配置错误监控、链路追踪、会话重放或日志功能
用户提及
```
@sentry/svelte
```
、
```
@sentry/sveltekit
```
或Sentry的Svelte SDK

注意： 以下SDK版本和API基于编写时的最新Sentry文档（
@sentry/sveltekit
≥10.8.0，SvelteKit ≥2.31.0）。实施前请务必对照Sentry官方文档进行验证。

Phase 1: Detect

阶段1：项目检测

Run these commands to understand the project before making any recommendations:

bash

undefined

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

bash

undefined

Detect framework type

检测框架类型

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

Check for SvelteKit indicators

检查SvelteKit相关文件

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)

检查SvelteKit版本（决定使用哪种设置模式）

cat package.json | grep '"@sveltejs/kit"'

Check if Sentry is already installed

检查是否已安装Sentry

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)

检测日志库（Node端）

cat package.json | grep -E '"pino"|"winston"|"consola"'

Detect if there's a backend (Go, Python, Ruby, etc.) in adjacent directories

检测相邻目录中是否存在后端服务（Go、Python、Ruby等）

ls ../backend ../server ../api 2>/dev/null cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3


**What to determine:**

| Question | Impact |
|----------|--------|
| `@sveltejs/kit` in `package.json`? | SvelteKit path vs. plain Svelte path |
| SvelteKit ≥2.31.0? | Modern (`instrumentation.server.ts`) vs. legacy setup |
| `@sentry/sveltekit` already present? | Skip install, go straight to feature config |
| `vite.config.ts` present? | Source map upload via Vite plugin available |
| Backend directory found? | Trigger Phase 4 cross-link suggestion |

---

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的跨服务关联建议 |

---

Phase 2: Recommend

阶段2：配置建议

Present a concrete recommendation based on what you found. Don't ask open-ended questions — lead with a proposal:

Recommended (core coverage):

✅ Error Monitoring — always; auto-captures unhandled errors on client and server
✅ Tracing — SvelteKit has both client-side navigation spans and server-side request spans; always recommend
✅ Session Replay — recommended for user-facing SvelteKit apps (client-side only)

Optional (enhanced observability):

⚡ Logging — structured logs via
```
Sentry.logger.*
```
; recommend when app uses server-side logging or needs log-to-trace correlation

Recommendation logic:

Feature	Recommend when...
Error Monitoring	Always — non-negotiable baseline
Tracing	Always for SvelteKit (client + server); for plain Svelte when calling APIs
Session Replay	User-facing app, login flows, or checkout pages present
Logging	App already uses server-side logging, or structured log search is needed

Propose: "I recommend setting up Error Monitoring + Tracing + Session Replay. Want me to also add structured Logging?"

根据检测结果给出具体建议，避免开放式问题，直接给出方案：

推荐配置（核心覆盖）：

✅ 错误监控 — 必选；自动捕获客户端和服务端的未处理错误
✅ 链路追踪 — SvelteKit支持客户端导航链路和服务端请求链路；必选
✅ 会话重放 — 推荐面向用户的SvelteKit应用使用（仅客户端）

可选配置（增强可观测性）：

⚡ 日志功能 — 通过
```
Sentry.logger.*
```
实现结构化日志；当应用使用服务端日志或需要日志与链路关联时推荐

推荐逻辑：

功能	推荐场景
错误监控	始终推荐 — 不可缺少的基础功能
链路追踪	SvelteKit应用始终推荐（客户端+服务端）；纯Svelte应用在调用API时推荐
会话重放	面向用户的应用、登录流程或结账页面存在时推荐
日志功能	应用已使用服务端日志，或需要结构化日志搜索时推荐

建议话术：“我建议设置错误监控+链路追踪+会话重放。是否需要同时添加结构化日志功能？”

Phase 3: Guide

阶段3：分步引导

Determine Setup Path

确定设置路径

Your project	Package	Setup complexity
SvelteKit (≥2.31.0)	`@sentry/sveltekit`	5 files to create/modify
SvelteKit (<2.31.0)	`@sentry/sveltekit`	3 files (init in hooks.server.ts)
Plain Svelte (no `@sveltejs/kit` )	`@sentry/svelte`	Single entry point

项目类型	使用包	设置复杂度
SvelteKit（≥2.31.0）	`@sentry/sveltekit`	需要创建/修改5个文件
SvelteKit（<2.31.0）	`@sentry/sveltekit`	需要修改3个文件（在hooks.server.ts中初始化）
纯Svelte（无 `@sveltejs/kit` ）	`@sentry/svelte`	仅需配置单个入口文件

Path A: SvelteKit (Recommended — Modern, ≥2.31.0)

路径A：SvelteKit（推荐——现代版，≥2.31.0）

Option 1: Wizard (Easiest)

选项1：向导工具（最简单）

bash

npx @sentry/wizard@latest -i sveltekit

The wizard creates all necessary files automatically, uploads source maps, and adds a

/sentry-example-page

for verification. Skip to Verification after running it.

bash

npx @sentry/wizard@latest -i sveltekit

向导工具会自动创建所有必要文件、上传源码映射，并添加一个

/sentry-example-page

用于验证。运行完成后直接跳至验证步骤。

Option 2: Manual Setup

选项2：手动设置

Step 1 — Install

bash

npm install @sentry/sveltekit --save

Step 2 —
svelte.config.js
— Enable instrumentation

javascript

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

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

export default config;

Step 3 —
src/instrumentation.server.ts
— Server-side init (runs once at startup)

typescript

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

Step 4 —
src/hooks.client.ts
— Client-side init

typescript

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();

Step 5 —
src/hooks.server.ts
— Server hooks (no init here in modern setup)

typescript

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

Step 6 —
vite.config.ts
— Source maps (requires

SENTRY_AUTH_TOKEN

)

typescript

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

Add to

.env

(never commit):

bash

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

步骤1 — 安装依赖

bash

npm install @sentry/sveltekit --save

步骤2 — 修改
svelte.config.js
— 启用工具集成

javascript

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
— 服务端初始化（启动时运行一次）

typescript

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,    // 生产环境建议降低至0.1–0.2
  enableLogs: true,
});

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

typescript

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
— 服务端钩子（现代设置中无需在此初始化）

typescript

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

export const handleError = Sentry.handleErrorWithSentry();

// sentryHandle() 会监控 incoming 请求并创建根链路
export const handle = Sentry.sentryHandle();

// 如果有其他handle函数，使用sequence()组合：
// export const handle = sequence(Sentry.sentryHandle(), myAuthHandle);

步骤6 — 修改
vite.config.ts
— 源码映射配置（需要

SENTRY_AUTH_TOKEN

）

typescript

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

export default defineConfig({
  plugins: [
    // sentrySvelteKit 必须在 sveltekit() 之前
    sentrySvelteKit({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
    sveltekit(),
  ],
});

在

.env

中添加以下环境变量（请勿提交到版本库）：

bash

SENTRY_AUTH_TOKEN=sntrys_...
SENTRY_ORG=my-org-slug
SENTRY_PROJECT=my-project-slug

Path B: SvelteKit Legacy (<2.31.0 or

@sentry/sveltekit

<10.8.0)

路径B：旧版SvelteKit（<2.31.0 或

@sentry/sveltekit

<10.8.0）

Skip

instrumentation.server.ts

and

svelte.config.js

changes. Instead, put

Sentry.init()

directly in

hooks.server.ts

typescript

// 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

and

vite.config.ts

are identical to the modern path.

跳过

instrumentation.server.ts

和

svelte.config.js

的修改，直接在

hooks.server.ts

中添加

Sentry.init()

：

typescript

// src/hooks.server.ts（旧版——初始化代码在此）
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

的配置与现代路径完全一致。

Path C: Plain Svelte (no SvelteKit)

路径C：纯Svelte（无SvelteKit）

Install:

bash

npm install @sentry/svelte --save

Configure in entry point (

src/main.ts

src/main.js

) before mounting the app:

typescript

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;

Optional: Svelte component tracking (auto-injects tracking into all components):

javascript

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

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

安装依赖：

bash

npm install @sentry/svelte --save

在入口文件（
src/main.ts
或
src/main.js
）中配置，需在挂载应用前完成：

typescript

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组件追踪（自动向所有组件注入追踪代码）：

javascript

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

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

For Each Agreed Feature

针对每个确认的功能

Walk through features one at a time. Load the reference file, follow its steps, then verify before moving on:

Feature	Reference	Load when...
Error Monitoring	`${SKILL_ROOT}/references/error-monitoring.md`	Always (baseline)
Tracing	`${SKILL_ROOT}/references/tracing.md`	API calls / distributed tracing needed
Session Replay	`${SKILL_ROOT}/references/session-replay.md`	User-facing app
Logging	`${SKILL_ROOT}/references/logging.md`	Structured logs / log-to-trace correlation

For each feature:

Read ${SKILL_ROOT}/references/<feature>.md

, follow steps exactly, verify it works.

逐个配置功能，加载参考文件，按照步骤操作，验证后再进行下一步：

功能	参考文件	加载场景
错误监控	`${SKILL_ROOT}/references/error-monitoring.md`	始终加载（基础功能）
链路追踪	`${SKILL_ROOT}/references/tracing.md`	需要API调用/分布式追踪时
会话重放	`${SKILL_ROOT}/references/session-replay.md`	面向用户的应用
日志功能	`${SKILL_ROOT}/references/logging.md`	需要结构化日志/日志与链路关联时

对于每个功能：读取

${SKILL_ROOT}/references/<feature>.md

，严格按照步骤操作，验证功能正常运行。

SvelteKit File Summary

SvelteKit文件汇总

File	Purpose	Modern	Legacy
`src/instrumentation.server.ts`	Server `Sentry.init()` — runs once at startup	✅ Required	❌
`src/hooks.client.ts`	Client `Sentry.init()` + `handleError`	✅ Required	✅ Required
`src/hooks.server.ts`	`handleError` + `sentryHandle()` (no init)	✅ Required	✅ Init goes here
`svelte.config.js`	Enable `experimental.instrumentation.server`	✅ Required	❌
`vite.config.ts`	`sentrySvelteKit()` plugin for source maps	✅ Recommended	✅ Recommended
`.env`	`SENTRY_AUTH_TOKEN` , `SENTRY_ORG` , `SENTRY_PROJECT`	✅ For source maps	✅ For source maps

文件	用途	现代设置	旧版设置
`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`	✅ 用于源码映射	✅ 用于源码映射

Configuration Reference

配置参考

Key

Sentry.init()

Options

Sentry.init()

关键选项

Option	Type	Default	Notes
`dsn`	`string`	—	Required. Use env var; SDK is disabled when empty
`environment`	`string`	`"production"`	e.g., `"staging"` , `"development"`
`release`	`string`	—	e.g., `"my-app@1.2.3"` or git SHA
`sendDefaultPii`	`boolean`	`false`	Includes IP addresses and request headers
`tracesSampleRate`	`number`	—	0–1; use `1.0` in dev, `0.1–0.2` in prod
`tracesSampler`	`function`	—	Per-transaction sampling; overrides `tracesSampleRate`
`tracePropagationTargets`	`(string\|RegExp)[]`	—	URLs that receive distributed tracing headers
`replaysSessionSampleRate`	`number`	—	Fraction of all sessions recorded (client only)
`replaysOnErrorSampleRate`	`number`	—	Fraction of error sessions recorded (client only)
`enableLogs`	`boolean`	`false`	Enable `Sentry.logger.*` API
`beforeSendLog`	`function`	—	Filter/modify logs before send
`debug`	`boolean`	`false`	Verbose SDK output to console

选项	类型	默认值	说明
`dsn`	`string`	—	必填。使用环境变量；为空时SDK会禁用
`environment`	`string`	`"production"`	例如： `"staging"` 、 `"development"`
`release`	`string`	—	例如： `"my-app@1.2.3"` 或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日志

Server-Only Options (

instrumentation.server.ts

hooks.server.ts

)

服务端专属选项（

instrumentation.server.ts

hooks.server.ts

）

Option	Type	Notes
`serverName`	`string`	Hostname tag on server events
`includeLocalVariables`	`boolean`	Attach local vars to stack frames
`shutdownTimeout`	`number`	ms to flush events before process exit (default: 2000)

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

Adapter Compatibility

适配器兼容性

Adapter	Support
`@sveltejs/adapter-auto` / adapter-vercel (Node)	✅ Full
`@sveltejs/adapter-node`	✅ Full
`@sveltejs/adapter-cloudflare`	⚠️ Partial — requires extra setup
Vercel Edge Runtime	❌ Not supported

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

Verification

验证步骤

After setup, trigger test events to confirm Sentry is receiving data:

svelte

<!-- src/routes/sentry-test/+page.svelte -->
<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>

typescript

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

Check the Sentry dashboard:

Issues → both errors should appear within seconds
Traces → look for route-based transactions
Replays → session recording visible after page interaction
Logs → structured log entries (if logging enabled)

If nothing appears, set

debug: true

Sentry.init()

and check the browser/server console for SDK output.

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

svelte

<!-- src/routes/sentry-test/+page.svelte -->
<script>
  import * as Sentry from "@sentry/sveltekit";
</script>

<button onclick={() => { throw new Error("Sentry client test"); }}>
  测试客户端错误
</button>

<button onclick={() => Sentry.captureMessage("Sentry test message", "info")}>
  测试消息上报
</button>

typescript

// 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输出。

Phase 4: Cross-Link

阶段4：跨服务关联

After completing Svelte/SvelteKit setup, check for a companion backend missing Sentry coverage:

bash

undefined

完成Svelte/SvelteKit设置后，检查是否存在未配置Sentry的关联后端服务：

bash

undefined

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


If a backend exists without Sentry configured, suggest the matching skill:

| Backend detected | Suggest skill |
|-----------------|--------------|
| Go (`go.mod`) | `sentry-go-sdk` |
| Python (`requirements.txt`, `pyproject.toml`) | `sentry-python-sdk` |
| Ruby (`Gemfile`) | `sentry-ruby-sdk` |
| Node.js (Express, Fastify, etc.) | Use `@sentry/node` — see [docs.sentry.io/platforms/javascript/guides/express/](https://docs.sentry.io/platforms/javascript/guides/express/) |

---

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`——参考[Sentry官方文档](https://docs.sentry.io/platforms/javascript/guides/express/) |

---

Troubleshooting

故障排除

Issue	Solution
Events not appearing	Set `debug: true` , check DSN, open browser console for SDK errors
Source maps not working	Run `npm run build` (not `dev` ), verify `SENTRY_AUTH_TOKEN` is set
Server errors not captured	Ensure `handleErrorWithSentry()` is exported from `hooks.server.ts`
Client errors not captured	Ensure `handleErrorWithSentry()` is exported from `hooks.client.ts`
Session replay not recording	Confirm `replayIntegration()` is in client init only (never server)
`sentryHandle()` + other handles not composing	Wrap with `sequence(Sentry.sentryHandle(), myHandle)`
Ad-blocker blocking events	Set `tunnel: "/sentry-tunnel"` and add a server-side relay endpoint
SvelteKit instrumentation not activating	Confirm `experimental.instrumentation.server: true` in `svelte.config.js`
Cloudflare adapter issues	Consult docs.sentry.io/platforms/javascript/guides/sveltekit/ for adapter-specific notes
`wrapLoadWithSentry` / `wrapServerLoadWithSentry` errors	These are legacy wrappers — remove them; `sentryHandle()` instruments load functions automatically in ≥10.8.0

问题	解决方案
事件未上报	设置 `debug: true` ，检查DSN是否正确，查看浏览器/服务端控制台的SDK错误信息
源码映射不生效	运行 `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适配器问题	参考Sentry官方文档中的适配器专属说明
`wrapLoadWithSentry` / `wrapServerLoadWithSentry` 报错	这些是旧版包装函数——请移除；≥10.8.0版本中 `sentryHandle()` 会自动监控load函数

sentry-svelte-sdk

Original

Translation

Sentry Svelte SDK

Sentry Svelte SDK

Invoke This Skill When

何时使用本指南

Phase 1: Detect

阶段1：项目检测

Detect framework type

检测框架类型

Check for SvelteKit indicators

检查SvelteKit相关文件

Check SvelteKit version (determines which setup pattern to use)

检查SvelteKit版本（决定使用哪种设置模式）

Check if Sentry is already installed

检查是否已安装Sentry

Check existing hook files

检查现有钩子文件

Detect logging libraries (Node side)

检测日志库（Node端）

Detect if there's a backend (Go, Python, Ruby, etc.) in adjacent directories

检测相邻目录中是否存在后端服务（Go、Python、Ruby等）

Phase 2: Recommend

阶段2：配置建议

Phase 3: Guide

阶段3：分步引导

Determine Setup Path

确定设置路径

Path A: SvelteKit (Recommended — Modern, ≥2.31.0)

路径A：SvelteKit（推荐——现代版，≥2.31.0）

Option 1: Wizard (Easiest)

选项1：向导工具（最简单）

Option 2: Manual Setup

选项2：手动设置

Path B: SvelteKit Legacy (<2.31.0 or @sentry/sveltekit <10.8.0)

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

Path C: Plain Svelte (no SvelteKit)

路径C：纯Svelte（无SvelteKit）

For Each Agreed Feature

针对每个确认的功能

SvelteKit File Summary

SvelteKit文件汇总

Configuration Reference

配置参考

Key Sentry.init() Options

Sentry.init()关键选项

Server-Only Options (instrumentation.server.ts / hooks.server.ts)

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

Adapter Compatibility

适配器兼容性

Verification

验证步骤

Phase 4: Cross-Link

阶段4：跨服务关联

Look for backend in adjacent directories

查找相邻目录中的后端服务

Troubleshooting

故障排除

Path B: SvelteKit Legacy (<2.31.0 or
`@sentry/sveltekit`
<10.8.0)

路径B：旧版SvelteKit（<2.31.0 或
`@sentry/sveltekit`
<10.8.0）

Key
`Sentry.init()`
Options

`Sentry.init()`
关键选项

Server-Only Options (
`instrumentation.server.ts`
/
`hooks.server.ts`
)

服务端专属选项（
`instrumentation.server.ts`
/
`hooks.server.ts`
）