⚡

依赖升级管理 dependency-upgrade

依赖升级管理技能专注于处理软件依赖库的重大版本升级，包括兼容性分析、分阶段升级策略和全面测试方法。适用于框架升级、安全漏洞修复和库的破坏性变更管理，关键词：依赖管理、版本升级、兼容性测试、自动化更新、DevOps、CI/CD、安全修复。

DevOps 0 次安装 0 次浏览 更新于 3/7/2026

name: 依赖升级 description: 管理重大依赖版本升级，包括兼容性分析、分阶段部署和全面测试。用于升级框架版本、更新重大依赖或管理库中的破坏性变更。 license: MIT

依赖升级

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

何时使用此技能

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

语义版本控制回顾

MAJOR.MINOR.PATCH (例如：2.3.1)

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

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

依赖分析

审计依赖（首选Bun）

# 首选：Bun
bun outdated
bun audit

# npm
npm outdated
npm audit
npm audit fix

# yarn
yarn outdated
yarn audit

# 检查重大更新
bunx npm-check-updates
bunx npm-check-updates -u  # 更新package.json

分析依赖树

# 查看为什么安装某个包
npm ls package-name
yarn why package-name

# 查找重复包
npm dedupe
yarn dedupe

# 可视化依赖
bunx 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 "升级顺序：
1. TypeScript
2. React
3. React Router
4. 测试库
5. 构建工具" > UPGRADE_PLAN.md

阶段2：增量更新（首选Bun）

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

# 步骤1：更新TypeScript（首选）
bun add -D typescript@latest

# 或使用npm
bun add typescript@latest

# 测试（首选）
bun test
bun run build

# 或使用npm
npm run test
npm run build

# 步骤2：更新React（一次升级一个主要版本）
# 首选
bun add react@17 react-dom@17

# 或使用npm
bun add react@17 react-dom@17

# 再次测试（首选）
bun test

# 或使用npm
npm run test

# 步骤3：继续其他包
# 首选
bun add react-router-dom@6

# 或使用npm
bun add react-router-dom@6

# 以此类推...

阶段3：验证

// tests/compatibility.test.js
describe('依赖兼容性', () => {
  it('应具有兼容的React版本', () => {
    const reactVersion = require('react/package.json').version;
    const reactDomVersion = require('react-dom/package.json').version;

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

  it('不应有对等依赖警告', () => {
    // 运行npm ls并检查警告
  });
});

破坏性变更处理

识别破坏性变更

# 使用更新日志解析器
bunx changelog-parser react 16.0.0 17.0.0

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

用于自动修复的Codemod

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

# 示例：更新生命周期方法
bunx 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

// 如果需要，更新测试工具
bun add @testing-library/react@latest

集成测试

// tests/integration/app.test.js
describe('应用集成', () => {
  it('应渲染而不崩溃', () => {
    render(<App />);
  });

  it('应处理导航', () => {
    const { getByText } = render(<App />);
    fireEvent.click(getByText('Navigate'));
    expect(screen.getByText('新页面')).toBeInTheDocument();
  });
});

视觉回归测试

// visual-regression.test.js
describe('视觉回归', () => {
  it('应匹配快照', () => {
    const { container } = render(<App />);
    expect(container.firstChild).toMatchSnapshot();
  });
});

端到端测试

// cypress/e2e/app.cy.js
describe('端到端测试', () => {
  it('应完成用户流程', () => {
    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

# 尝试升级
bun add package@latest

# 运行测试
if npm run test; then
  echo "升级成功"
  git add package.json package-lock.json
  git commit -m "chore: upgrade package"
else
  echo "升级失败，回滚中"
  git checkout main
  git branch -D upgrade-branch
  npm install  # 从package-lock.json恢复
fi

常见升级模式

锁定文件管理（首选Bun）

# 首选：Bun
bun install --frozen-lockfile

# npm
npm install --package-lock-only  # 仅更新锁定文件
npm ci  # 从锁定文件清洁安装

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

对等依赖解决

# npm 7+: 严格对等依赖
npm install --legacy-peer-deps  # 忽略对等依赖

# npm 8+: 覆盖对等依赖
npm install --force

工作区升级

# 更新所有工作区包
npm install --workspaces

# 更新特定工作区
bun add 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. 首选Bun: 尽可能使用Bun进行安装、脚本和测试
  2. 阅读更新日志: 了解变更内容
  3. 增量升级: 一次升级一个主要版本
  4. 全面测试: 单元、集成、端到端测试
  5. 检查对等依赖: 早期解决冲突
  6. 使用锁定文件: 确保可重现安装
  7. 自动化更新: 使用Renovate或Dependabot
  8. 监控: 升级后观察运行时错误
  9. 文档: 保持升级笔记

升级检查清单

升级前：
- [ ] 审查当前依赖版本
- [ ] 阅读更新日志中的破坏性变更
- [ ] 创建功能分支
- [ ] 备份当前状态（git标签）
- [ ] 运行完整测试套件（基线）

升级期间：
- [ ] 一次升级一个依赖
- [ ] 更新对等依赖
- [ ] 修复TypeScript错误
- [ ] 如果需要，更新测试
- [ ] 每次升级后运行测试套件
- [ ] 检查包大小影响

升级后：
- [ ] 全面回归测试
- [ ] 性能测试
- [ ] 更新文档
- [ ] 部署到暂存环境
- [ ] 监控错误
- [ ] 部署到生产环境

常见陷阱

  • 一次性升级所有依赖
  • 每次升级后未测试
  • 忽略对等依赖警告
  • 忘记更新锁定文件
  • 未阅读破坏性变更笔记
  • 跳过主要版本
  • 没有回滚计划