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迁移（从事务到跨度）
复杂配置重构（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」）
确认是否执行所有变更或特定分类的变更
注意：v8→v9迁移可使用CLI替代方案
```
npx @sentry/wizard -i upgrade
```
，但可能无法处理所有模式

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。