From 08564ca2128a45dc3cc47483f645b3e975de3480 Mon Sep 17 00:00:00 2001 From: wehub-skill-sync Date: Mon, 13 Jul 2026 21:37:07 +0800 Subject: [PATCH] chore: import zh skill dependency-upgrade --- README.wehub.md | 9 ++ SKILL.md | 367 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 376 insertions(+) create mode 100644 README.wehub.md create mode 100644 SKILL.md diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..f3fff19 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,9 @@ +# WeHub 来源说明 + +- Skill 名称：`dependency-upgrade` +- 中文类目：依赖树/版本矩阵驱动的升级规划 +- 上游仓库：`wshobson__agents` +- 上游路径：`plugins/framework-migration/skills/dependency-upgrade/SKILL.md` +- 上游链接：https://github.com/wshobson/agents/blob/HEAD/plugins/framework-migration/skills/dependency-upgrade/SKILL.md +- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..fa0ed99 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,367 @@ +--- +name: dependency-upgrade +description: 管理主要依赖版本升级，包含兼容性分析、分阶段发布与全面测试。适用于框架版本升级、主要依赖更新或处理库的破坏性变更。 + +# 依赖升级 + +掌握主要依赖版本升级、兼容性分析、分阶段升级策略及全面测试方法。 + +## 何时使用本技能 + +- 升级主要框架版本 +- 更新存在安全漏洞的依赖 +- 现代化遗留依赖 +- 解决依赖冲突 +- 规划增量升级路径 +- 测试兼容性矩阵 +- 自动化依赖更新 + +## 语义化版本回顾 + +``` +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 +# npm +npm outdated +npm audit +npm audit fix + +# yarn +yarn outdated +yarn audit + +# 检查主要更新 +npx npm-check-updates +npx npm-check-updates -u # 更新 package.json +``` + +### 分析依赖树 + +```bash +# 查看某个包的安装原因 +npm ls package-name +yarn why package-name + +# 查找重复包 +npm dedupe +yarn dedupe + +# 可视化依赖关系 +npx madge --image graph.png src/ +``` + +## 兼容性矩阵 + +```javascript +// 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) { + // 根据矩阵校验包版本 +} +``` + +## 分阶段升级策略 + +### 阶段一：规划 + +```bash +# 1. 识别当前版本 +npm list --depth=0 + +# 2. 检查破坏性变更 +# 阅读 CHANGELOG.md 和 MIGRATION.md + +# 3. 创建升级计划 +echo "升级顺序： +1. TypeScript +2. React +3. React Router +4. 测试库 +5. 构建工具" > UPGRADE_PLAN.md +``` + +### 阶段二：增量更新 + +```bash +# 不要一次性全部升级！ + +# 第 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 + +# 以此类推…… +``` + +### 阶段三：验证 + +```javascript +// 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 并检查警告 + }); +}); +``` + +## 破坏性变更处理 + +### 识别破坏性变更 + +```bash +# 直接查看 changelog +curl https://raw.githubusercontent.com/facebook/react/master/CHANGELOG.md +``` + +### 使用 Codemod 进行自动修复 + +```bash +# 使用 transform URL 运行 jscodeshift +npx jscodeshift -t + +# 示例：重命名不安全的生命周期方法 +npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/ + +# 针对 TypeScript 文件 +npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --parser=tsx src/ + +# 空跑以预览变更 +npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --dry src/ +``` + +### 自定义迁移脚本 + +```javascript +// 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); + }); +}); +``` + +## 测试策略 + +### 单元测试 + +```javascript +// 确保升级前后测试通过 +npm run test + +// 根据需要更新测试工具 +npm install @testing-library/react@latest +``` + +### 集成测试 + +```javascript +// tests/integration/app.test.js +describe("应用集成", () => { + it("应能正常渲染而不崩溃", () => { + render(); + }); + + it("应能处理导航", () => { + const { getByText } = render(); + fireEvent.click(getByText("Navigate")); + expect(screen.getByText("New Page")).toBeInTheDocument(); + }); +}); +``` + +### 视觉回归测试 + +```javascript +// visual-regression.test.js +describe("视觉回归", () => { + it("应与快照匹配", () => { + const { container } = render(); + expect(container.firstChild).toMatchSnapshot(); + }); +}); +``` + +### E2E 测试 + +```javascript +// cypress/e2e/app.cy.js +describe("E2E 测试", () => { + 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 配置 + +```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.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" +``` + +## 回滚计划 + +```javascript +// rollback.sh +#!/bin/bash + +# 保存当前状态 +git stash +git checkout -b upgrade-branch + +# 尝试升级 +npm install 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 +``` + +## 常见升级模式 + +### 锁文件管理 + +```bash +# npm +npm install --package-lock-only # 仅更新锁文件 +npm ci # 从锁文件执行干净安装 + +# yarn +yarn install --frozen-lockfile # CI 模式 +yarn upgrade-interactive # 交互式升级 +``` + +### 对等依赖解析 + +```bash +# npm 7+：严格对等依赖 +npm install --legacy-peer-deps # 忽略对等依赖 + +# npm 8+：覆盖对等依赖 +npm install --force +``` + +### 工作区升级 + +```bash +# 更新所有工作区包 +npm install --workspaces + +# 更新特定工作区 +npm install package@latest --workspace=packages/app +```