sentry-sdk-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

All Skills > Workflow > SDK Upgrade

所有技能 > 工作流 > SDK 升级

Sentry JavaScript SDK Upgrade

Sentry JavaScript SDK 升级指南

Upgrade the Sentry JavaScript SDK across major versions with AI-guided migration.

借助AI引导的迁移流程，跨大版本升级Sentry JavaScript SDK。

Invoke This Skill When

何时调用此技能

User asks to "upgrade Sentry" or "migrate Sentry SDK"
User mentions deprecated Sentry APIs or breaking changes after a version bump
User wants to move from v7 to v8, v8 to v9, or any major version jump
User encounters errors after updating
```
@sentry/*
```
package versions
User asks about Sentry migration guides or changelogs

用户要求"升级Sentry"或"迁移Sentry SDK"
用户提到已弃用的Sentry API或版本升级后的破坏性变更
用户希望从v7升级到v8、v8升级到v9，或进行任意大版本跳跃
用户更新
```
@sentry/*
```
包版本后遇到错误
用户询问Sentry迁移指南或变更日志

Phase 1: Detect

阶段1：检测

Identify the current Sentry SDK version, target version, and framework.

识别当前Sentry SDK版本、目标版本及所使用的框架。

1.1 Read package.json

1.1 读取package.json

bash

cat package.json | grep -E '"@sentry/' | head -20

Extract:

All
```
@sentry/*
```
packages and their current versions
The current major version (e.g.,
```
7.x
```
,
```
8.x
```
,
```
9.x
```
)

bash

cat package.json | grep -E '"@sentry/' | head -20

提取以下信息：

所有
```
@sentry/*
```
包及其当前版本
当前大版本（例如：
```
7.x
```
、
```
8.x
```
、
```
9.x
```
）

1.2 Detect Framework

1.2 检测框架

Check

package.json

dependencies for framework indicators:

Dependency	Framework	Sentry Package
`next`	Next.js	`@sentry/nextjs`
`nuxt` or `@nuxt/kit`	Nuxt	`@sentry/nuxt`
`@sveltejs/kit`	SvelteKit	`@sentry/sveltekit`
`@remix-run/node`	Remix	`@sentry/remix`
`react` (no Next/Remix)	React SPA	`@sentry/react`
`@angular/core`	Angular	`@sentry/angular`
`vue` (no Nuxt)	Vue	`@sentry/vue`
`express`	Express	`@sentry/node`
`@nestjs/core`	NestJS	`@sentry/nestjs`
`@solidjs/start`	SolidStart	`@sentry/solidstart`
`astro`	Astro	`@sentry/astro`
`bun` types or runtime	Bun	`@sentry/bun`
`@cloudflare/workers-types`	Cloudflare	`@sentry/cloudflare`
None of above (Node.js)	Node.js	`@sentry/node`

检查

package.json

中的依赖包以识别框架：

依赖包	框架	Sentry 包
`next`	Next.js	`@sentry/nextjs`
`nuxt` 或 `@nuxt/kit`	Nuxt	`@sentry/nuxt`
`@sveltejs/kit`	SvelteKit	`@sentry/sveltekit`
`@remix-run/node`	Remix	`@sentry/remix`
`react` （非Next/Remix）	React 单页应用	`@sentry/react`
`@angular/core`	Angular	`@sentry/angular`
`vue` （非Nuxt）	Vue	`@sentry/vue`
`express`	Express	`@sentry/node`
`@nestjs/core`	NestJS	`@sentry/nestjs`
`@solidjs/start`	SolidStart	`@sentry/solidstart`
`astro`	Astro	`@sentry/astro`
`bun` 类型或运行时	Bun	`@sentry/bun`
`@cloudflare/workers-types`	Cloudflare	`@sentry/cloudflare`
以上均不满足（Node.js）	Node.js	`@sentry/node`

1.3 Find Sentry Config Files

1.3 查找Sentry配置文件

bash

grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -l

bash

find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next | grep -v .nuxt

bash

grep -rn "from '@sentry/\|require('@sentry/" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" --include="*.mjs" --include="*.cjs" -l

bash

find . -name "sentry.*" -o -name "*.sentry.*" -o -name "instrumentation.*" | grep -v node_modules | grep -v .next | grep -v .nuxt

1.4 Detect Deprecated Patterns

1.4 检测已弃用的代码模式

Scan for patterns that indicate which migration steps are needed:

bash

undefined

扫描代码以确定需要哪些迁移步骤：

bash

undefined

v7 patterns (need v7→v8 migration)

v7 代码模式（需进行v7→v8迁移）

v8 patterns (need v8→v9 migration)

v8 代码模式（需进行v8→v9迁移）

grep -rn "from '@sentry/utils'|from '@sentry/types'" --include=".ts" --include=".js" --include=".tsx" --include=".jsx" -l grep -rn "getCurrentHub|enableTracing|captureUserFeedback|@WithSentry|autoSessionTracking" --include=".ts" --include=".js" --include=".tsx" --include=".jsx" -l

undefined

undefined

1.5 Determine Target Version

1.5 确定目标版本

If the user didn't specify a target version, recommend the latest major version (v9 as of this writing). If the user has already bumped package versions but has broken code, detect the target from

package.json

如果用户未指定目标版本，推荐最新大版本（本文档撰写时为v9）。如果用户已升级包版本但代码出现问题，则从

package.json

中检测目标版本。

Phase 2: Recommend

阶段2：推荐方案

Present a migration summary based on detected state.

基于检测到的状态，呈现迁移总结。

2.1 Calculate Migration Path

2.1 规划迁移路径

Single hop: e.g., v8 to v9
Multi-hop: e.g., v7 to v9 (apply v7→v8 changes first, then v8→v9)

For multi-hop migrations, apply code changes incrementally but update package versions once to the final target.

单步迁移：例如从v8升级到v9
多步迁移：例如从v7升级到v9（先应用v7→v8的变更，再应用v8→v9的变更）

对于多步迁移，需逐步应用代码变更，但包版本可一次性更新至最终目标版本。

2.2 Present Breaking Changes Summary

2.2 呈现破坏性变更总结

Load the appropriate version-specific reference:

v7→v8: references/v7-to-v8.md
v8→v9: references/v8-to-v9.md
v9→v10: references/v9-to-v10.md

Present a concrete summary of changes needed, categorized by complexity:

Auto-fixable (apply directly):

Package import renames (e.g.,
```
@sentry/utils
```
to
```
@sentry/core
```
)
Simple method renames (e.g.,
```
@WithSentry
```
to
```
@SentryExceptionCaptured
```
)
Config option swaps (e.g.,
```
enableTracing
```
to
```
tracesSampleRate
```
)

AI-assisted (explain and propose):

Hub removal with variable storage patterns
Performance API migration (transactions to spans)
Complex config restructuring (Vue tracing options, Next.js config merging)
Sampler
```
transactionContext
```
flattening

Manual review (flag for user):

Removed APIs with no equivalent
Behavioral changes (sampling, source maps defaults)
Custom transport modifications

加载对应版本的参考文档：

v7→v8：references/v7-to-v8.md
v8→v9：references/v8-to-v9.md
v9→v10：references/v9-to-v10.md

按复杂度分类呈现需要的具体变更：

可自动修复（直接应用）：

包导入重命名（例如：
```
@sentry/utils
```
改为
```
@sentry/core
```
）
简单方法重命名（例如：
```
@WithSentry
```
改为
```
@SentryExceptionCaptured
```
）
配置选项替换（例如：
```
enableTracing
```
改为
```
tracesSampleRate
```
）

AI辅助修复（解释并提供方案）：

移除Hub并调整变量存储模式
性能API迁移（从事务到Span）
复杂配置重构（Vue追踪选项、Next.js配置合并）
采样器
```
transactionContext
```
扁平化

需人工审核（标记给用户确认）：

无替代方案的已移除API
行为变更（采样、Source Maps默认设置）
自定义传输层修改

2.3 Confirm Scope

2.3 确认范围

Ask the user:

Confirm the migration path (e.g., "v8 to v9")
Confirm whether to proceed with all changes or specific categories
Note:
```
npx @sentry/wizard -i upgrade
```
exists as a CLI alternative for v8→v9 but may not handle all patterns

询问用户：

确认迁移路径（例如："v8 到 v9"）
确认是否要应用所有变更或仅特定分类的变更
注意：
```
npx @sentry/wizard -i upgrade
```
是v8→v9迁移的CLI替代方案，但可能无法处理所有代码模式

Phase 3: Guide

阶段3：分步指导

Step through changes file by file.

逐文件指导变更操作。

3.1 Process Each File with Sentry Imports

3.1 处理所有包含Sentry导入的文件

For each file identified in Phase 1.3:

Read the file to understand current Sentry usage
Apply auto-fixable changes directly:
- Package import renames
- Method/function renames
- Simple config option swaps
For AI-assisted changes, explain what needs to change and why, then propose the specific edit
For uncertain changes, show the code and ask the user to confirm

对于阶段1.3中识别的每个文件：

读取文件以理解当前Sentry的使用方式
直接应用可自动修复的变更：
- 包导入重命名
- 方法/函数重命名
- 简单配置选项替换
对于AI辅助修复的变更，解释需要修改的内容及原因，然后提供具体的编辑建议
对于不确定的变更，展示代码并询问用户确认

3.2 Apply Changes by Category

3.2 按分类应用变更

Work through changes in this order:

按以下顺序处理变更：

Step 1: Package Import Updates

步骤1：更新包导入

Replace removed/renamed package imports. Reference the version-specific migration file for the complete mapping.

替换已移除或重命名的包导入。请参考对应版本的迁移文档获取完整映射关系。

Step 2: API Renames

步骤2：API重命名

Apply mechanical method and function renames.

执行方法和函数的机械重命名。

Step 3: Config Changes

步骤3：配置变更

Update

Sentry.init()

options and build configuration.

更新

Sentry.init()

选项及构建配置。

Step 4: Complex Pattern Migration

步骤4：复杂模式迁移

Handle patterns requiring understanding of context:

Hub usage stored in variables
Transaction-based performance code
Custom integration classes
Framework-specific wrappers

处理需要结合上下文理解的代码模式：

存储在变量中的Hub使用
基于事务的性能代码
自定义集成类
框架特定的包装器

Step 5: Update package.json Versions

步骤5：更新package.json中的版本

Update all

@sentry/*

packages to the target version. All packages must be on the same major version.

bash

undefined

将所有

@sentry/*

包更新至目标版本。所有包必须使用相同的大版本。

bash

undefined

Detect package manager

检测包管理器

if [ -f "yarn.lock" ]; then echo "yarn" elif [ -f "pnpm-lock.yaml" ]; then echo "pnpm" else echo "npm" fi


Install updated dependencies using the detected package manager.

if [ -f "yarn.lock" ]; then echo "yarn" elif [ -f "pnpm-lock.yaml" ]; then echo "pnpm" else echo "npm" fi


使用检测到的包管理器安装更新后的依赖。

Step 6: Verify Build

步骤6：验证构建

bash

undefined

bash

undefined

Check for type errors

检查类型错误

npx tsc --noEmit 2>&1 | head -50

Run build

执行构建

npm run build 2>&1 | tail -20


Fix any remaining type errors or build failures.

npm run build 2>&1 | tail -20


修复所有剩余的类型错误或构建失败问题。

3.3 Framework-Specific Steps

3.3 框架特定步骤

Consult references/upgrade-patterns.md for framework-specific config file locations and validation steps.

Next.js: Check

instrumentation.ts

next.config.ts

wrapper, both client and server configs. Nuxt: Check Nuxt module config and both plugin files. SvelteKit: Check hooks files and Vite config. Express/Node: Verify early initialization order. NestJS: Check for decorator and filter renames.

请参考references/upgrade-patterns.md获取框架特定的配置文件位置及验证步骤。

Next.js：检查

instrumentation.ts

、

next.config.ts

包装器、客户端和服务端配置。 Nuxt：检查Nuxt模块配置及两个插件文件。 SvelteKit：检查hooks文件和Vite配置。 Express/Node：验证初始化顺序是否正确。 NestJS：检查装饰器和过滤器的重命名。

Phase 4: Cross-Link

阶段4：交叉验证与扩展

4.1 Verify

4.1 验证

All
```
@sentry/*
```
packages on same version
No import errors from removed packages
TypeScript compilation passes
Build succeeds
Tests pass (if they exist)

Suggest adding a test error:

// Add temporarily to verify Sentry is working after upgrade
setTimeout(() => {
  throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);

所有
```
@sentry/*
```
包使用相同版本
无已移除包的导入错误
TypeScript编译通过
构建成功
测试通过（若存在测试）

建议添加测试错误以验证：

// 临时添加以验证Sentry升级后是否正常工作，可安全删除
setTimeout(() => {
  throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);

4.2 New Features in Target Version

4.2 目标版本的新特性

Mention features available in the new version that the user might want to enable:

v8 new features: OpenTelemetry-based Node tracing, automatic database/HTTP instrumentation, functional integrations, new span APIs

v9 new features: Structured logging (

Sentry.logger.*

), improved source maps handling, simplified configuration

介绍用户可能想要启用的新版本特性：

v8新特性：基于OpenTelemetry的Node追踪、自动数据库/HTTP instrumentation、函数式集成、新的Span API

v9新特性：结构化日志（

Sentry.logger.*

）、改进的Source Maps处理、简化的配置

4.3 Related Resources

4.3 相关资源

If the user has other Sentry SDKs (Python, Ruby, Go, etc.) that also need upgrading, note that this skill covers JavaScript SDK only.

如果用户还有其他需要升级的Sentry SDK（如Python、Ruby、Go等），请注意本技能仅覆盖JavaScript SDK。