升级 Sentry JavaScript SDK…

当需要将 Sentry JavaScript SDK 跨大版本升级（如 v7→v8、v8→v9）或修复升级后的废弃 API 与破坏性变更时使用。

适用场景

解决思路

1. 读取 package.json 中所有 @sentry/* 包及其版本，确定当前主版本（如 7.x、8.x、9.x）。
2. 根据 package.json 依赖检测框架并映射到对应的 Sentry 包：next→@sentry/nextjs，nuxt 或 @nuxt/kit→@sentry/nuxt，@sveltejs/kit→@sentry/sveltekit，@remix-run/node→@sentry/remix，react（无 Next/Remix）→@sentry/react，@angular/core→@sentry/angular，vue（无 Nuxt）→@sentry/vue，express→@sentry/node，@nestjs/core→@sentry/nestjs，@solidjs/start→@sentry/solidstart，astro→@sentry/astro，bun 类型或运行时→@sentry/bun，@cloudflare/workers-types→@sentry/cloudflare，以上都没有（Node.js）→@sentry/node。
3. 用 grep 搜索所有从 @sentry/ 导入的文件，并用 find 查找 sentry.*、*.sentry.*、instrumentation.* 配置文件（排除 node_modules、.next、.nuxt）。
4. 扫描废弃模式以确定需要的迁移步骤：v7 模式包括 from '@sentry/hub'、from '@sentry/tracing'、from '@sentry/integrations'、from '@sentry/serverless'、from '@sentry/replay'、new BrowserTracing、new Replay、startTransaction、configureScope、Handlers.requestHandler、Handlers.errorHandler；v8 模式包括 from '@sentry/utils'、from '@sentry/types'、getCurrentHub、enableTracing、captureUserFeedback、@WithSentry、autoSessionTracking。
5. 若用户未指定目标版本，推荐最新主版本（当前为 v9）；若用户已升级包版本但代码报错，则从 package.json 检测目标版本。
6. 计算迁移路径：单跳（如 v8→v9）或多跳（如 v7→v9，先应用 v7→v8 变更再应用 v8→v9）；多跳时增量应用代码变更，但包版本一次性更新到最终目标。
7. 加载对应版本迁移参考（v7→v8、v8→v9、v9→v10），按复杂度分类呈现变更：可直接自动修复（包导入重命名、简单方法重命名、配置项替换）、AI 辅助（Hub 移除与变量存储模式、性能 API 从 transaction 迁移到 span、复杂配置重构、sampler transactionContext 扁平化）、需人工审查（无等价替代的已移除 API、行为变更、自定义 transport 修改）。
8. 与用户确认迁移路径、是否执行全部变更或特定类别；注意 npx @sentry/wizard -i upgrade 可作为 v8→v9 的 CLI 替代方案，但可能无法覆盖所有模式。
9. 逐文件处理：读取文件理解当前 Sentry 用法，直接应用可自动修复的变更，对 AI 辅助变更解释原因并给出具体修改，对不确定的变更展示代码请用户确认。
10. 按顺序应用变更：先更新包导入，再应用 API 重命名，然后更新 Sentry.init() 选项和构建配置，接着处理复杂模式（变量中存储的 Hub、基于 transaction 的性能代码、自定义集成类、框架特定包装器），最后更新 package.json 版本。
11. 将所有 @sentry/* 包更新到目标版本，确保所有包处于同一主版本；检测包管理器（yarn.lock→yarn，pnpm-lock.yaml→pnpm，否则 npm）并安装依赖。
12. 验证构建：运行 npx tsc --noEmit 检查类型错误，运行 npm run build 检查构建，修复剩余的类型错误或构建失败。
13. 按框架执行特定步骤：Next.js 检查 instrumentation.ts、next.config.ts 包装器及客户端和服务端配置；Nuxt 检查 Nuxt 模块配置和两个插件文件；SvelteKit 检查 hooks 文件和 Vite 配置；Express/Node 验证早期初始化顺序；NestJS 检查装饰器和过滤器重命名。
14. 最终验证清单：所有 @sentry/* 包版本一致、无已移除包的导入错误、TypeScript 编译通过、构建成功、测试通过（如有）；可临时添加 setTimeout(() => { throw new Error('Sentry upgrade verification - safe to delete'); }, 3000) 验证 Sentry 正常工作。
15. 告知用户目标版本的新特性：v8 有基于 OpenTelemetry 的 Node 追踪、自动数据库/HTTP 插桩、函数式集成、新 span API；v9 有结构化日志（Sentry.logger.*）、改进的 source map 处理、简化配置。
16. 参考官方迁移指南（v7→v8、v8→v9）和 Sentry JavaScript SDK Changelog；若用户还有其他 Sentry SDK（Python、Ruby、Go 等）需要升级，说明本技能仅覆盖 JavaScript SDK。

适用边界 · 注意事项

• 仅需升级非 JavaScript 的 Sentry SDK（如 Python、Ruby、Go）时。
• 不涉及跨大版本升级或废弃 API 修复的常规 Sentry 使用问题时。