Dependency Upgrade

掌握主要依赖版本升级、兼容性分析、分阶段升级策略和全面测试方法。当用户要求'升级依赖'、'版本升级'、'依赖更新'、'处理依赖冲突'时使用。

kscz0000 Updated Sep 21, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add kscz0000/dependency-upgrade

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

Download SKILL.md

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/kscz0000/dependency-upgrade.svg)](https://skillmd.com/skills/kscz0000/dependency-upgrade)

Trust & safety

Audits pending

Not yet audited · commit 78cf5b0

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Dependency Upgrade

掌握主要依赖版本升级、兼容性分析、分阶段升级策略和全面测试方法。

不适用场景

任务与依赖升级无关
需要此范围之外的其他领域或工具

使用说明

明确目标、约束条件和所需输入。
应用相关最佳实践并验证结果。
提供可执行的步骤和验证方法。
如需详细示例，请打开 resources/implementation-playbook.md。

适用场景

升级主要框架版本
更新存在安全漏洞的依赖
现代化遗留依赖
解决依赖冲突
规划增量升级路径
测试兼容性矩阵
自动化依赖更新

语义版本控制回顾

MAJOR.MINOR.PATCH (例如: 2.3.1)

MAJOR: 破坏性变更
MINOR: 新功能，向后兼容
PATCH: Bug修复，向后兼容

^2.3.1 = >=2.3.1 <3.0.0 (次版本更新)
~2.3.1 = >=2.3.1 <2.4.0 (补丁更新)
2.3.1 = 精确版本

依赖分析

审计依赖

# npm
npm outdated
npm audit
npm audit fix

# yarn
yarn outdated
yarn audit

# 检查主要更新
npx npm-check-updates
npx npm-check-updates -u  # 更新 package.json

分析依赖树

# 查看包为何被安装
npm ls package-name
yarn why package-name

# 查找重复包
npm dedupe
yarn dedupe

# 可视化依赖
npx madge --image graph.png src/

兼容性矩阵

// compatibility-matrix.js
const compatibilityMatrix = {
  'react': {
    '16.x': {
      'react-dom': '^16.0.0',
      'react-router-dom': '^5.0.0',
      '@testing-library/react': '^11.0.0'
    },
    '17.x': {
      'react-dom': '^17.0.0',
      'react-router-dom': '^5.0.0 || ^6.0.0',
      '@testing-library/react': '^12.0.0'
    },
    '18.x': {
      'react-dom': '^18.0.0',
      'react-router-dom': '^6.0.0',
      '@testing-library/react': '^13.0.0'
    }
  }
};

function checkCompatibility(packages) {
  // 根据矩阵验证包版本
}

分阶段升级策略

阶段1：规划

# 1. 确认当前版本
npm list --depth=0

# 2. 检查破坏性变更
# 阅读 CHANGELOG.md 和 MIGRATION.md

# 3. 创建升级计划
echo "Upgrade order:
1. TypeScript
2. React
3. React Router
4. Testing libraries
5. Build tools" > UPGRADE_PLAN.md

阶段2：增量更新

# 不要一次性升级所有内容！

# 步骤1：更新 TypeScript
npm install typescript@latest

# 测试
npm run test
npm run build

# 步骤2：更新 React（一次升级一个主版本）
npm install react@17 react-dom@17

# 再次测试
npm run test

# 步骤3：继续其他包
npm install react-router-dom@6

# 以此类推...

阶段3：验证

// tests/compatibility.test.js
describe('Dependency Compatibility', () => {
  it('should have compatible React versions', () => {
    const reactVersion = require('react/package.json').version;
    const reactDomVersion = require('react-dom/package.json').version;

    expect(reactVersion).toBe(reactDomVersion);
  });

  it('should not have peer dependency warnings', () => {
    // 运行 npm ls 并检查警告
  });
});

破坏性变更处理

识别破坏性变更

# 使用 changelog 解析器
npx changelog-parser react 16.0.0 17.0.0

# 或手动检查
curl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md

使用 Codemod 自动修复

# React 升级 codemods
npx react-codeshift <transform> <path>

# 示例：更新生命周期方法
npx react-codeshift \
  --parser tsx \
  --transform react-codeshift/transforms/rename-unsafe-lifecycles.js \
  src/

自定义迁移脚本

// migration-script.js
const fs = require('fs');
const glob = require('glob');

glob('src/**/*.tsx', (err, files) => {
  files.forEach(file => {
    let content = fs.readFileSync(file, 'utf8');

    // 将旧 API 替换为新 API
    content = content.replace(
      /componentWillMount/g,
      'UNSAFE_componentWillMount'
    );

    // 更新导入
    content = content.replace(
      /import { Component } from 'react'/g,
      "import React, { Component } from 'react'"
    );

    fs.writeFileSync(file, content);
  });
});

测试策略

单元测试

// 确保升级前后测试都通过
npm run test

// 如需要，更新测试工具
npm install @testing-library/react@latest

集成测试

// tests/integration/app.test.js
describe('App Integration', () => {
  it('should render without crashing', () => {
    render(<App />);
  });

  it('should handle navigation', () => {
    const { getByText } = render(<App />);
    fireEvent.click(getByText('Navigate'));
    expect(screen.getByText('New Page')).toBeInTheDocument();
  });
});

视觉回归测试

// visual-regression.test.js
describe('Visual Regression', () => {
  it('should match snapshot', () => {
    const { container } = render(<App />);
    expect(container.firstChild).toMatchSnapshot();
  });
});

E2E 测试

// cypress/e2e/app.cy.js
describe('E2E Tests', () => {
  it('should complete user flow', () => {
    cy.visit('/');
    cy.get('[data-testid="login"]').click();
    cy.get('input[name="email"]').type('user@example.com');
    cy.get('button[type="submit"]').click();
    cy.url().should('include', '/dashboard');
  });
});

自动化依赖更新

Renovate 配置

// renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["major-update"]
    }
  ],
  "schedule": ["before 3am on Monday"],
  "timezone": "America/New_York"
}

Dependabot 配置

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    reviewers:
      - "team-leads"
    commit-message:
      prefix: "chore"
      include: "scope"

回滚计划

// rollback.sh
#!/bin/bash

# 保存当前状态
git stash
git checkout -b upgrade-branch

# 尝试升级
npm install package@latest

# 运行测试
if npm run test; then
  echo "Upgrade successful"
  git add package.json package-lock.json
  git commit -m "chore: upgrade package"
else
  echo "Upgrade failed, rolling back"
  git checkout main
  git branch -D upgrade-branch
  npm install  # 从 package-lock.json 恢复
fi

常见升级模式

锁文件管理

# npm
npm install --package-lock-only  # 仅更新锁文件
npm ci  # 从锁文件干净安装

# yarn
yarn install --frozen-lockfile  # CI 模式
yarn upgrade-interactive  # 交互式升级

Peer Dependency 解决方案

# npm 7+: 严格的 peer dependencies
npm install --legacy-peer-deps  # 忽略 peer deps

# npm 8+: 覆盖 peer dependencies
npm install --force

Workspace 升级

# 更新所有 workspace 包
npm install --workspaces

# 更新特定 workspace
npm install package@latest --workspace=packages/app

资源

references/semver.md: 语义版本控制指南
references/compatibility-matrix.md: 常见兼容性问题
references/staged-upgrades.md: 增量升级策略
references/testing-strategy.md: 全面测试方法
assets/upgrade-checklist.md: 逐步检查清单
assets/compatibility-matrix.csv: 版本兼容性表
scripts/audit-dependencies.sh: 依赖审计脚本

最佳实践

阅读 Changelog：理解变更内容
增量升级：一次升级一个主版本
充分测试：单元测试、集成测试、E2E测试
检查 Peer Dependencies：尽早解决冲突
使用锁文件：确保可复现安装
自动化更新：使用 Renovate 或 Dependabot
监控：关注升级后的运行时错误
文档记录：保留升级笔记

升级检查清单

升级前：
- [ ] 检查当前依赖版本
- [ ] 阅读 changelog 了解破坏性变更
- [ ] 创建功能分支
- [ ] 备份当前状态（git tag）
- [ ] 运行完整测试套件（基线）

升级中：
- [ ] 一次升级一个依赖
- [ ] 更新 peer dependencies
- [ ] 修复 TypeScript 错误
- [ ] 如需要，更新测试
- [ ] 每次升级后运行测试套件
- [ ] 检查打包体积影响

升级后：
- [ ] 完整回归测试
- [ ] 性能测试
- [ ] 更新文档
- [ ] 部署到预发布环境
- [ ] 监控错误
- [ ] 部署到生产环境

常见陷阱

一次性升级所有依赖
每次升级后不测试
忽略 peer dependency 警告
忘记更新锁文件
不阅读破坏性变更说明
跳过主版本
没有回滚计划

局限性

仅当任务明确符合上述范围时使用此技能。
不要将输出视为环境特定验证、测试或专家审查的替代品。
如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。

---name: dependency-upgradedescription: 掌握主要依赖版本升级、兼容性分析、分阶段升级策略和全面测试方法。当用户要求'升级依赖'、'版本升级'、'依赖更新'、'处理依赖冲突'时使用。---# Dependency Upgrade掌握主要依赖版本升级、兼容性分析、分阶段升级策略和全面测试方法。## 不适用场景- 任务与依赖升级无关- 需要此范围之外的其他领域或工具## 使用说明- 明确目标、约束条件和所需输入。- 应用相关最佳实践并验证结果。- 提供可执行的步骤和验证方法。- 如需详细示例，请打开 `resources/implementation-playbook.md`。## 适用场景- 升级主要框架版本- 更新存在安全漏洞的依赖- 现代化遗留依赖- 解决依赖冲突- 规划增量升级路径- 测试兼容性矩阵- 自动化依赖更新## 语义版本控制回顾```MAJOR.MINOR.PATCH (例如: 2.3.1)MAJOR: 破坏性变更MINOR: 新功能，向后兼容PATCH: Bug修复，向后兼容^2.3.1 = >=2.3.1 <3.0.0 (次版本更新)~2.3.1 = >=2.3.1 <2.4.0 (补丁更新)2.3.1 = 精确版本```## 依赖分析### 审计依赖```bash# npmnpm outdatednpm auditnpm audit fix# yarnyarn outdatedyarn audit# 检查主要更新npx npm-check-updatesnpx npm-check-updates -u # 更新 package.json```### 分析依赖树```bash# 查看包为何被安装npm ls package-nameyarn why package-name# 查找重复包npm dedupeyarn dedupe# 可视化依赖npx madge --image graph.png src/```## 兼容性矩阵```javascript// compatibility-matrix.jsconst compatibilityMatrix = { 'react': { '16.x': { 'react-dom': '^16.0.0', 'react-router-dom': '^5.0.0', '@testing-library/react': '^11.0.0' }, '17.x': { 'react-dom': '^17.0.0', 'react-router-dom': '^5.0.0 || ^6.0.0', '@testing-library/react': '^12.0.0' }, '18.x': { 'react-dom': '^18.0.0', 'react-router-dom': '^6.0.0', '@testing-library/react': '^13.0.0' } }};function checkCompatibility(packages) { // 根据矩阵验证包版本}```## 分阶段升级策略### 阶段1：规划```bash# 1. 确认当前版本npm list --depth=0# 2. 检查破坏性变更# 阅读 CHANGELOG.md 和 MIGRATION.md# 3. 创建升级计划echo "Upgrade order:1. TypeScript2. React3. React Router4. Testing libraries5. Build tools" > UPGRADE_PLAN.md```### 阶段2：增量更新```bash# 不要一次性升级所有内容！# 步骤1：更新 TypeScriptnpm install typescript@latest# 测试npm run testnpm run build# 步骤2：更新 React（一次升级一个主版本）npm install react@17 react-dom@17# 再次测试npm run test# 步骤3：继续其他包npm install react-router-dom@6# 以此类推...```### 阶段3：验证```javascript// tests/compatibility.test.jsdescribe('Dependency Compatibility', () => { it('should have compatible React versions', () => { const reactVersion = require('react/package.json').version; const reactDomVersion = require('react-dom/package.json').version; expect(reactVersion).toBe(reactDomVersion); }); it('should not have peer dependency warnings', () => { // 运行 npm ls 并检查警告 });});```## 破坏性变更处理### 识别破坏性变更```bash# 使用 changelog 解析器npx changelog-parser react 16.0.0 17.0.0# 或手动检查curl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md```### 使用 Codemod 自动修复```bash# React 升级 codemodsnpx react-codeshift <transform> <path># 示例：更新生命周期方法npx react-codeshift \ --parser tsx \ --transform react-codeshift/transforms/rename-unsafe-lifecycles.js \ src/```### 自定义迁移脚本```javascript// migration-script.jsconst fs = require('fs');const glob = require('glob');glob('src/**/*.tsx', (err, files) => { files.forEach(file => { let content = fs.readFileSync(file, 'utf8'); // 将旧 API 替换为新 API content = content.replace( /componentWillMount/g, 'UNSAFE_componentWillMount' ); // 更新导入 content = content.replace( /import { Component } from 'react'/g, "import React, { Component } from 'react'" ); fs.writeFileSync(file, content); });});```## 测试策略### 单元测试```javascript// 确保升级前后测试都通过npm run test// 如需要，更新测试工具npm install @testing-library/react@latest```### 集成测试```javascript// tests/integration/app.test.jsdescribe('App Integration', () => { it('should render without crashing', () => { render(<App />); }); it('should handle navigation', () => { const { getByText } = render(<App />); fireEvent.click(getByText('Navigate')); expect(screen.getByText('New Page')).toBeInTheDocument(); });});```### 视觉回归测试```javascript// visual-regression.test.jsdescribe('Visual Regression', () => { it('should match snapshot', () => { const { container } = render(<App />); expect(container.firstChild).toMatchSnapshot(); });});```### E2E 测试```javascript// cypress/e2e/app.cy.jsdescribe('E2E Tests', () => { it('should complete user flow', () => { cy.visit('/'); cy.get('[data-testid="login"]').click(); cy.get('input[name="email"]').type('user@example.com'); cy.get('button[type="submit"]').click(); cy.url().should('include', '/dashboard'); });});```## 自动化依赖更新### Renovate 配置```json// renovate.json{ "extends": ["config:base"], "packageRules": [ { "matchUpdateTypes": ["minor", "patch"], "automerge": true }, { "matchUpdateTypes": ["major"], "automerge": false, "labels": ["major-update"] } ], "schedule": ["before 3am on Monday"], "timezone": "America/New_York"}```### Dependabot 配置```yaml# .github/dependabot.ymlversion: 2updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" open-pull-requests-limit: 5 reviewers: - "team-leads" commit-message: prefix: "chore" include: "scope"```## 回滚计划```javascript// rollback.sh#!/bin/bash# 保存当前状态git stashgit checkout -b upgrade-branch# 尝试升级npm install package@latest# 运行测试if npm run test; then echo "Upgrade successful" git add package.json package-lock.json git commit -m "chore: upgrade package"else echo "Upgrade failed, rolling back" git checkout main git branch -D upgrade-branch npm install # 从 package-lock.json 恢复fi```## 常见升级模式### 锁文件管理```bash# npmnpm install --package-lock-only # 仅更新锁文件npm ci # 从锁文件干净安装# yarnyarn install --frozen-lockfile # CI 模式yarn upgrade-interactive # 交互式升级```### Peer Dependency 解决方案```bash# npm 7+: 严格的 peer dependenciesnpm install --legacy-peer-deps # 忽略 peer deps# npm 8+: 覆盖 peer dependenciesnpm install --force```### Workspace 升级```bash# 更新所有 workspace 包npm install --workspaces# 更新特定 workspacenpm install package@latest --workspace=packages/app```## 资源- **references/semver.md**: 语义版本控制指南- **references/compatibility-matrix.md**: 常见兼容性问题- **references/staged-upgrades.md**: 增量升级策略- **references/testing-strategy.md**: 全面测试方法- **assets/upgrade-checklist.md**: 逐步检查清单- **assets/compatibility-matrix.csv**: 版本兼容性表- **scripts/audit-dependencies.sh**: 依赖审计脚本## 最佳实践1. **阅读 Changelog**：理解变更内容2. **增量升级**：一次升级一个主版本3. **充分测试**：单元测试、集成测试、E2E测试4. **检查 Peer Dependencies**：尽早解决冲突5. **使用锁文件**：确保可复现安装6. **自动化更新**：使用 Renovate 或 Dependabot7. **监控**：关注升级后的运行时错误8. **文档记录**：保留升级笔记## 升级检查清单```markdown升级前：- [ ] 检查当前依赖版本- [ ] 阅读 changelog 了解破坏性变更- [ ] 创建功能分支- [ ] 备份当前状态（git tag）- [ ] 运行完整测试套件（基线）升级中：- [ ] 一次升级一个依赖- [ ] 更新 peer dependencies- [ ] 修复 TypeScript 错误- [ ] 如需要，更新测试- [ ] 每次升级后运行测试套件- [ ] 检查打包体积影响升级后：- [ ] 完整回归测试- [ ] 性能测试- [ ] 更新文档- [ ] 部署到预发布环境- [ ] 监控错误- [ ] 部署到生产环境```## 常见陷阱- 一次性升级所有依赖- 每次升级后不测试- 忽略 peer dependency 警告- 忘记更新锁文件- 不阅读破坏性变更说明- 跳过主版本- 没有回滚计划## 局限性- 仅当任务明确符合上述范围时使用此技能。- 不要将输出视为环境特定验证、测试或专家审查的替代品。- 如果缺少所需输入、权限、安全边界或成功标准，请停下来请求澄清。

kscz0000/antigravity-awesome-skills-CN/tree/main/反重力 - 超强技能 - 中文/skills/后端开发/依赖打包/dependency-upgrade commit 78cf5b00de

Frequently asked questions

npx skillmds@latest add kscz0000/dependency-upgrade