sentry-sdk-upgrade

所有技能 > 工作流 > 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、8.x、9.x）

1.2 检测框架

检查 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 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

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 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 确定目标版本

如果用户未指定目标版本，建议使用最新主版本（截至本文撰写时为 v9）。如果用户已升级软件包版本但代码无法运行，则从 package.json 中检测目标版本。

阶段 2：提出建议

根据检测到的状态，提供迁移摘要。

2.1 计算迁移路径

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

对于多步迁移，逐步应用代码更改，但只需将软件包版本更新一次，直接升级到最终目标版本。

2.2 提供破坏性变更摘要

加载相应版本的参考资料：

• 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 迁移（从事务迁移到 spans）
• 复杂的配置重构（Vue 跟踪选项、Next.js 配置合并）
• 扁平化采样器的 transactionContext

需手动审核（提示用户）：

• 已移除且没有等效替代项的 API
• 行为变更（采样、默认 source maps）
• 自定义传输修改

2.3 确认范围

询问用户：

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

阶段 3：引导迁移

逐个文件处理更改。

3.1 处理每个导入 Sentry 的文件

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

1. 阅读文件，了解当前的 Sentry 用法
2. 直接应用可自动修复的更改：
   • 包导入重命名
   • 方法／函数重命名
   • 简单的配置选项替换
3. 对于 AI 辅助的更改，说明需要更改什么以及原因，然后提出具体的修改方案
4. 对于不确定的更改，展示代码并请用户确认

3.2 按类别应用更改

按以下顺序处理更改：

步骤 1：更新包导入

替换已移除／重命名的包导入。请参阅对应版本的迁移文件，了解完整映射。

步骤 2：API 重命名

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

步骤 3：配置更改

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

步骤 4：迁移复杂模式

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

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

步骤 5：更新 package.json 版本

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

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

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

步骤 6：验证构建

# Check for type errors
npx tsc --noEmit 2>&1 | head -50

# Run build
npm run build 2>&1 | tail -20

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

3.3 框架特定步骤

请参阅 references/upgrade-patterns.md，了解框架特定的配置文件位置和验证步骤。

Next.js：检查 instrumentation.ts、next.config.ts 封装器，以及客户端和服务端配置。 Nuxt：检查 Nuxt 模块配置和两个插件文件。 SvelteKit：检查 hooks 文件和 Vite 配置。 Express/Node：验证初始化顺序是否靠前。 NestJS：检查装饰器和筛选器的重命名。

阶段 4：交叉链接

4.1 验证

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

建议添加一个测试错误：

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

4.2 目标版本中的新功能

介绍新版本中可用且用户可能希望启用的功能：

v8 新功能：基于 OpenTelemetry 的 Node 追踪、自动数据库／HTTP 插桩、函数式集成、新的 span API

v9 新功能：结构化日志（Sentry.logger.*）、改进的 source map 处理、简化的配置

4.3 相关资源

• 官方迁移指南（v7→v8）
• 官方迁移指南（v8→v9）
• Sentry JavaScript SDK 更新日志

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