updating-npm-package

更新 npm 包

当用户要求更新、升级或提升特定 npm 依赖项的版本时，使用此技能。

步骤

1. 检查当前版本 — 阅读 package.json，找到已安装的版本：

   npm ls <package-name>
   

2. 在 npm 上查找最新版本 — 获取包信息：

   npm view <package-name> versions --json
   npm view <package-name> dist-tags --json
   

   这会提供 latest 标签和所有已发布的版本。

3. 确定更新类型 — 比较当前版本和最新版本：

   • 补丁版本（1.2.3 → 1.2.4）：仅修复错误
   • 次要版本（1.2.3 → 1.3.0）：添加新功能，向后兼容
   • 主要版本（1.2.3 → 2.0.0）：包含破坏性变更

4. 对于补丁或次要版本更新 — 直接更新：

   npm install <package-name>@latest
   

   运行构建和测试，确保一切正常：

   npm run build && npm test
   

   如果所有检查均通过，则提交更改并报告更新内容。

5. 对于主要版本更新 — 先进行全面调查：

   a. 获取更新日志和发布说明 — 查看该包的 GitHub 仓库，查找 CHANGELOG.md、MIGRATION.md 或发布说明。通过网络查找官方升级指南：

   Search: "<package-name> v<major> migration guide" OR "<package-name> v<major> upgrade guide"
   

   b. 阅读破坏性变更 — 找出当前版本与目标版本之间的所有破坏性变更。常见检查项：

   • 已移除或重命名的 API
   • 已更改的函数签名或返回类型
   • 已停止支持的 Node.js 版本
   • 新增的对等依赖要求
   • 已更改的默认行为
   • 配置文件格式变更

   c. 扫描代码库，评估影响 — 搜索该包的所有用法：

   # Find all imports
   grep -r "from ['\"]<package-name>" src/
   grep -r "require(['\"]<package-name>" src/
   

   对于每处用法，检查其是否会受到破坏性变更的影响。

   d. 应用更新：

   npm install <package-name>@latest
   

   e. 修复破坏性变更 — 根据迁移指南更新每处受影响的用法。逐个文件应用更改。

   f. 验证 — 运行完整测试套件：

   npm run lint && npx tsc --noEmit && npm test && npm run build
   

   g. 生成迁移报告 — 总结：

   ## Package Update: <package-name> v<old> → v<new> (Major)
   
   ### Breaking Changes Applied
   - `oldFunction()` renamed to `newFunction()` — updated in 3 files
   - Config format changed from `.js` to `.config.ts` — migrated
   - Dropped support for Node 16 — verified we're on Node 20
   
   ### Files Modified
   - src/lib/client.ts — updated import and function call
   - src/config/settings.ts — migrated config format
   - package.json — bumped version
   
   ### Validation
   - ✅ Lint passes
   - ✅ TypeScript compiles
   - ✅ All 47 tests pass
   - ✅ Build succeeds
   

注意事项

• 更新前务必检查对等依赖的兼容性 — npm install 会对版本不匹配发出警告。
• 对于 monorepo，检查该包是否在多个工作区中使用，并一并更新。
• 如果该包提供 codemod 工具（例如 npx @next/codemod），请使用该工具代替手动迁移。
• 锁文件（package-lock.json）的更改是预期之内的 — 请与更新一并提交。