Sentry JavaScript SDK 升级指南：AI引导跨版本迁移，解决弃用API与破坏性变更

sentry-sdk-upgrade by getsentry/sentry-for-ai

247 周安装量

82 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-sdk-upgrade

自动化 JavaScript 框架监控

🇨🇳中文介绍

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

Sentry JavaScript SDK 升级

通过 AI 引导的迁移，跨主要版本升级 Sentry JavaScript SDK。

何时调用此技能

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

阶段 1：检测

识别当前的 Sentry SDK 版本、目标版本和框架。

1.1 读取 package.json

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

提取：

所有 @sentry/* 包及其当前版本
当前主要版本（例如，7.x、、）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

1.3 查找 Sentry 配置文件

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

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

1.4 检测已弃用模式

扫描模式以确定需要哪些迁移步骤：

# v7 模式 (需要 v7→v8 迁移)
grep -rn "from '@sentry/hub'\|from '@sentry/tracing'\|from '@sentry/integrations'\|from '@sentry/serverless'\|from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l
grep -rn "new BrowserTracing\|new Replay\|startTransaction\|configureScope\|Handlers\.requestHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

# 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

1.5 确定目标版本

如果用户未指定目标版本，则推荐最新的主要版本（截至本文撰写时为 v9）。如果用户已经更新了包版本但代码已损坏，则从 package.json 中检测目标版本。

根据检测到的状态呈现迁移摘要。

2.1 计算迁移路径

单步迁移：例如，v8 到 v9
多步迁移：例如，v7 到 v9（先应用 v7→v8 的更改，然后应用 v8→v9 的更改）

对于多步迁移，增量应用代码更改，但将包版本一次性更新到最终目标。

2.2 呈现破坏性变更摘要

加载特定版本的参考文档：

按复杂性分类，呈现所需更改的具体摘要：

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

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

需要 AI 辅助的（解释并建议）：

使用变量存储模式的 Hub 移除
性能 API 迁移（事务到跨度）
复杂的配置重构（Vue 追踪选项，Next.js 配置合并）
采样器 transactionContext 扁平化

需要手动审查的（标记给用户）：

已移除且无等效项的 API
行为变更（采样、源映射默认值）
自定义传输器修改

确认迁移路径（例如，“v8 到 v9”）
确认是进行所有更改还是特定类别的更改
注意：npx @sentry/wizard -i upgrade 作为 v8→v9 的 CLI 替代方案存在，但可能无法处理所有模式

逐步指导每个文件的更改。

3.1 处理每个包含 Sentry 导入的文件

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

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

3.2 按类别应用更改

按以下顺序处理更改：

步骤 1：包导入更新

替换已移除/重命名的包导入。参考特定版本的迁移文件以获取完整的映射关系。

步骤 2：API 重命名

应用机械性的方法和函数重命名。

步骤 3：配置更改

更新 Sentry.init() 选项和构建配置。

步骤 4：复杂模式迁移

处理需要理解上下文的模式：

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

步骤 5：更新 package.json 版本

将所有 @sentry/* 包更新到目标版本。所有包必须处于相同的主要版本。

# 检测包管理器
if [ -f "yarn.lock" ]; then
  echo "yarn"
elif [ -f "pnpm-lock.yaml" ]; then
  echo "pnpm"
else
  echo "npm"
fi

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

步骤 6：验证构建

# 检查类型错误
npx tsc --noEmit 2>&1 | head -50

# 运行构建
npm run build 2>&1 | tail -20

修复任何剩余的类型错误或构建失败。

3.3 框架特定步骤

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

Next.js：检查 instrumentation.ts、next.config.ts 包装器、客户端和服务器配置。 Nuxt：检查 Nuxt 模块配置和两个插件文件。 SvelteKit：检查钩子文件和 Vite 配置。 Express/Node：验证早期初始化顺序。 NestJS：检查装饰器和过滤器重命名。

阶段 4：交叉链接

所有 @sentry/* 包版本一致
没有来自已移除包的导入错误
TypeScript 编译通过
构建成功
测试通过（如果存在）

建议添加一个测试错误：

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

4.2 目标版本中的新功能

提及新版本中用户可能希望启用的功能：

v8 新功能：基于 OpenTelemetry 的 Node 追踪、自动数据库/HTTP 检测、函数式集成、新的跨度 API

v9 新功能：结构化日志记录（Sentry.logger.*）、改进的源映射处理、简化的配置

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

🇺🇸English

All Skills > Workflow > SDK Upgrade

Sentry JavaScript SDK Upgrade

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

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

Phase 1: Detect

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

1.1 Read package.json

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)

1.2 Detect Framework

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`

1.3 Find Sentry Config Files

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



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

1.4 Detect Deprecated Patterns

Scan for patterns that indicate which migration steps are needed:

# v7 patterns (need v7→v8 migration)
grep -rn "from '@sentry/hub'\|from '@sentry/tracing'\|from '@sentry/integrations'\|from '@sentry/serverless'\|from '@sentry/replay'" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l
grep -rn "new BrowserTracing\|new Replay\|startTransaction\|configureScope\|Handlers\.requestHandler\|Handlers\.errorHandler" --include="*.ts" --include="*.js" --include="*.tsx" --include="*.jsx" -l

# v8 patterns (need v8→v9 migration)
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

1.5 Determine Target Version

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.

Phase 2: Recommend

Present a migration summary based on detected state.

2.1 Calculate Migration Path

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.

2.2 Present Breaking Changes Summary

Load the appropriate version-specific reference:

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

2.3 Confirm Scope

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

Phase 3: Guide

Step through changes file by file.

3.1 Process Each File with Sentry Imports

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

3.2 Apply Changes by Category

Work through changes in this order:

Step 1: Package Import Updates

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

Step 2: API Renames

Apply mechanical method and function renames.

Step 3: Config Changes

Update Sentry.init() options and build configuration.

Step 4: Complex Pattern Migration

Handle patterns requiring understanding of context:

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

Step 5: Update package.json Versions

Update all @sentry/* packages to the target version. All packages must be on the same major version.

# 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.

Step 6: Verify Build

# 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.

3.3 Framework-Specific Steps

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.

Phase 4: Cross-Link

4.1 Verify

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

4.2 New Features in Target Version

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

4.3 Related Resources

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

Weekly Installs

247

Repository

getsentry/sentry-for-ai

GitHub Stars

First Seen

Mar 4, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex244

github-copilot241

gemini-cli240

cursor240

opencode240

kimi-cli239

前端代码审计工具 - 自动化检测可访问性、性能、响应式设计、主题化与反模式

33,700 周安装

依赖项	框架	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 SPA	`@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`