sentry-sdk-upgrade by getsentry/sentry-for-ai
npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-sdk-upgrade通过 AI 引导的迁移,跨主要版本升级 Sentry JavaScript SDK。
@sentry/* 包版本后遇到错误识别当前的 Sentry SDK 版本、目标版本和框架。
cat package.json | grep -E '"@sentry/' | head -20
提取:
@sentry/* 包及其当前版本7.x、、)广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
8.x9.x检查 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 |
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
扫描模式以确定需要哪些迁移步骤:
# 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
如果用户未指定目标版本,则推荐最新的主要版本(截至本文撰写时为 v9)。如果用户已经更新了包版本但代码已损坏,则从 package.json 中检测目标版本。
根据检测到的状态呈现迁移摘要。
对于多步迁移,增量应用代码更改,但将包版本一次性更新到最终目标。
加载特定版本的参考文档:
按复杂性分类,呈现所需更改的具体摘要:
可自动修复的(直接应用):
@sentry/utils 改为 @sentry/core)@WithSentry 改为 @SentryExceptionCaptured)enableTracing 改为 tracesSampleRate)需要 AI 辅助的(解释并建议):
transactionContext 扁平化需要手动审查的(标记给用户):
询问用户:
npx @sentry/wizard -i upgrade 作为 v8→v9 的 CLI 替代方案存在,但可能无法处理所有模式逐步指导每个文件的更改。
对于阶段 1.3 中识别的每个文件:
按以下顺序处理更改:
替换已移除/重命名的包导入。参考特定版本的迁移文件以获取完整的映射关系。
应用机械性的方法和函数重命名。
更新 Sentry.init() 选项和构建配置。
处理需要理解上下文的模式:
将所有 @sentry/* 包更新到目标版本。所有包必须处于相同的主要版本。
# 检测包管理器
if [ -f "yarn.lock" ]; then
echo "yarn"
elif [ -f "pnpm-lock.yaml" ]; then
echo "pnpm"
else
echo "npm"
fi
使用检测到的包管理器安装更新后的依赖项。
# 检查类型错误
npx tsc --noEmit 2>&1 | head -50
# 运行构建
npm run build 2>&1 | tail -20
修复任何剩余的类型错误或构建失败。
参考 references/upgrade-patterns.md 获取框架特定的配置文件位置和验证步骤。
Next.js:检查 instrumentation.ts、next.config.ts 包装器、客户端和服务器配置。
Nuxt:检查 Nuxt 模块配置和两个插件文件。
SvelteKit:检查钩子文件和 Vite 配置。
Express/Node:验证早期初始化顺序。
NestJS:检查装饰器和过滤器重命名。
@sentry/* 包版本一致建议添加一个测试错误:
// 临时添加以验证升级后 Sentry 是否正常工作
setTimeout(() => {
throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);
提及新版本中用户可能希望启用的功能:
v8 新功能:基于 OpenTelemetry 的 Node 追踪、自动数据库/HTTP 检测、函数式集成、新的跨度 API
v9 新功能:结构化日志记录(Sentry.logger.*)、改进的源映射处理、简化的配置
如果用户还有其他需要升级的 Sentry SDK(Python、Ruby、Go 等),请注意此技能仅涵盖 JavaScript SDK。
每周安装数
247
仓库
GitHub 星标数
82
首次出现
2026年3月4日
安全审计
已安装于
codex244
github-copilot241
gemini-cli240
cursor240
opencode240
kimi-cli239
All Skills > Workflow > SDK Upgrade
Upgrade the Sentry JavaScript SDK across major versions with AI-guided migration.
@sentry/* package versionsIdentify the current Sentry SDK version, target version, and framework.
cat package.json | grep -E '"@sentry/' | head -20
Extract:
@sentry/* packages and their current versions7.x, 8.x, 9.x)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 |
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
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
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.
Present a migration summary based on detected state.
For multi-hop migrations, apply code changes incrementally but update package versions once to the final target.
Load the appropriate version-specific reference:
Present a concrete summary of changes needed, categorized by complexity:
Auto-fixable (apply directly):
@sentry/utils to @sentry/core)@WithSentry to @SentryExceptionCaptured)enableTracing to tracesSampleRate)AI-assisted (explain and propose):
transactionContext flatteningManual review (flag for user):
Ask the user:
npx @sentry/wizard -i upgrade exists as a CLI alternative for v8→v9 but may not handle all patternsStep through changes file by file.
For each file identified in Phase 1.3:
Work through changes in this order:
Replace removed/renamed package imports. Reference the version-specific migration file for the complete mapping.
Apply mechanical method and function renames.
Update Sentry.init() options and build configuration.
Handle patterns requiring understanding of context:
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.
# 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.
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.
@sentry/* packages on same versionSuggest adding a test error:
// Add temporarily to verify Sentry is working after upgrade
setTimeout(() => {
throw new Error('Sentry upgrade verification - safe to delete');
}, 3000);
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
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
GitHub Stars
82
First Seen
Mar 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex244
github-copilot241
gemini-cli240
cursor240
opencode240
kimi-cli239
前端代码审计工具 - 自动化检测可访问性、性能、响应式设计、主题化与反模式
33,700 周安装
@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 |