用途
此技能用于在用户要求更新、升级或提升某个具体 npm 依赖时,安全地完成版本更新。它覆盖从确认版本、判断更新类型到执行更新、修复破坏性变更并验证的完整流程。
主要能力
- 确认当前版本:读取 package.json,并用
npm ls <package-name>查找已安装版本。 - 查找最新版本:通过
npm view <package-name> versions --json和npm view <package-name> dist-tags --json获取 latest 标签与全部已发布版本。 - 判断更新类型:对比当前与最新版本,区分补丁(如 1.2.3 → 1.2.4,仅缺陷修复)、次要(如 1.2.3 → 1.3.0,新功能且向后兼容)、主要(如 1.2.3 → 2.0.0,破坏性变更)。
- 补丁或次要更新:直接执行
npm install <package-name>@latest,然后运行npm run build && npm test,通过后提交并报告变更。 - 主要版本更新:先做彻底调查,包括获取 changelog 与发布说明、搜索官方升级指南、识别破坏性变更(被移除或重命名的 API、变更的函数签名或返回类型、不再支持的 Node.js 版本、新的 peer dependency 要求、默认行为变化、配置文件格式变化等)。
- 影响扫描:用 grep 搜索代码库中所有导入与用法,例如
grep -r "from ['\"]<package-name>" src/与grep -r "require(['\"]<package-name>" src/,逐个核对是否受破坏性变更影响。 - 应用与修复:执行安装后,依据迁移指南逐文件修复受影响的用法。
- 验证与报告:运行
npm run lint && npx tsc --noEmit && npm test && npm run build,并生成迁移报告,包含破坏性变更、修改的文件与验证结果。
使用方式
该技能为面向代理的操作指南,由用户在提出更新某个 npm 包的需求时触发,代理按上述步骤执行。资料中给出了具体的 shell 命令与检查顺序,未提供交互式界面、安装命令或配置项。
适用场景
- 更新单个明确的 npm 依赖。
- 对次要/补丁更新做快速、可验证的升级。
- 对主要版本更新做破坏性变更调查与迁移。
限制与注意事项
- 更新前应始终检查 peer dependency 兼容性,
npm install会对不匹配给出警告。 - 在 monorepo 中需确认该包是否在多个 workspace 使用,并一并更新。
- 若该包提供 codemod 工具(例如
npx @next/codemod),应优先使用而非手动迁移。 - 锁文件(package-lock.json)的变更属于预期,应与本次更新一起提交。
- 资料未提供价格、收费、平台支持范围或效果保证等信息。