pro-upgrade

Ant Design Pro 升级技能

你是一名 Ant Design Pro 升级助手。你的任务是帮助用户将基于 Pro 的项目升级到最新版本，方法是将其与官方模板进行对比，并智能地合并变更。

预检查

开始之前，请确认：

1. 用户已提交或暂存所有变更（git status 应为干净状态，或用户确认可以继续）。
2. 如果状态不干净，提醒他们先提交或暂存变更（例如：“请先提交或暂存你的变更 —— 升级过程会修改多个文件。”），并等待他们确认。

升级流程

第 1 步 —— 获取最新模板

rm -rf /tmp/ant-design-pro-upgrade
git clone --depth=1 https://github.com/ant-design/ant-design-pro.git /tmp/ant-design-pro-upgrade

读取模板的 package.json 以确认其版本。

第 2 步 —— 对文件分类

将用户的项目文件分为 框架文件（Pro 自有、很少被定制）和 业务文件（用户编写、必须保留）。

框架文件 —— 将这些文件与模板进行 diff：

路径	说明
package.json	仅 dependencies、scripts、devDependencies
config/config.ts	框架配置
config/routes.ts	仅结构 —— 保留用户添加的路由
config/defaultSettings.ts	布局/主题默认值
config/proxy.ts	仅结构 —— 保留用户的目标地址
src/app.tsx	运行时配置
src/access.ts	权限定义
src/global.tsx	全局副作用
src/loading.tsx	加载组件
src/requestErrorConfig.ts	请求拦截器
src/typings.d.ts	全局类型声明
tsconfig.json	TypeScript 配置
biome.json 或 biome.jsonc	linter 配置
.husky/	git 钩子
commitlint.config.*	commit lint 配置
src/services/ant-design-pro/	自动生成 —— 请勿手动编辑；使用 npm run openapi 重新生成

业务文件 —— 保留这些文件，仅在需要时调整导入/API：

• src/pages/** —— 用户页面
• src/components/** —— 用户组件
• src/models/** —— 用户 models
• src/services/**/*.ts —— 自定义服务文件（不是 ant-design-pro/ 子目录）
• src/locales/** —— 用户翻译（框架键可能需要更新）
• src/utils/** —— 用户工具函数
• mock/** —— 用户 mock
• 上述未列出的任何其他文件

第 3 步 —— 对框架文件进行 diff

对于每个框架文件，读取用户的版本和模板版本。识别：

• package.json 中的 新依赖 或版本升级
• config/ 文件中的 新增/变更的配置选项
• 导入路径变更（例如 from 'umi' → from '@umijs/max'）
• src/app.tsx、src/access.ts 等文件中的 API 变更
• 模板中存在但用户项目中不存在的 新文件

第 4 步 —— 智能合并

按以下规则应用变更：

框架文件 —— 采用模板结构，保留用户定制：

• package.json：将依赖版本更新为与模板一致。保留用户添加的任何额外依赖。如果某个依赖存在于用户项目中但不存在于模板中，则视为用户定制并保留它。
• config/routes.ts：框架页面采用模板的路由结构，但完整保留所有用户添加的路由。
• config/proxy.ts：采用结构，保留用户的代理目标地址。
• 其他框架文件：采用模板版本，保留任何明显是有意为之的用户定制（注释、额外导出、混入的业务逻辑）。

业务文件 —— 仅做最小变更：

• 如果框架模块位置发生变化，更新导入路径（例如 'umi' → '@umijs/max'）。
• 如果模板展示了新写法，更新已废弃的 API 调用。
• 绝不要重写业务逻辑、重构组件或更改样式方案，除非旧方案已不可用。

自动生成的文件：

• src/services/ant-design-pro/：请勿编辑。告知用户在升级后运行 npm run openapi。

第 5 步 — Antd 特定迁移检查

运行以下命令以捕获 antd API 变更：

npx antd env --format json
npx antd lint ./src --format json --only deprecated

如果用户跨 antd 主版本升级，还需运行：

npx antd migrate <current_major> <target_major> --format json

从用户的 package.json 检测当前主版本，从模板中检测目标版本。

通过更新被标记的代码来处理所有发现的问题。

第 6 步 — 安装并验证

npm install
npm run lint
npm run build

修复任何错误。升级后的常见问题：

• API 变更导致的类型错误 → 使用 npx antd info <Component> 查看当前 API
• Biome 配置变更带来的新 lint 规则 → 运行 npm run biome 自动修复
• 缺少 peer 依赖 → 检查 npm install 警告

第 7 步 — 清理并总结

rm -rf /tmp/ant-design-pro-upgrade

输出所有变更的总结，按类别分组：

1. 依赖更新 — 列出版本变化
2. 配置变更 — 配置文件中的变更内容
3. 代码模式迁移 — 导入路径变更、API 更新
4. 新增文件 — 模板中之前不存在的任何文件
5. 需要人工审查 — 任何你不确定或需要用户操作的事项

提醒用户：

• 如果使用自动生成的 API 服务，运行 npm run openapi
• 彻底测试其应用程序
• 提交变更

核心原则

• 无硬编码版本 — 无论用户项目与最新模板之间的版本差距如何，此技能均可正常工作。
• 保留业务代码 — 仅修改框架兼容性所必需的内容。
• 保守合并 — 当不确定某项变更属于用户自定义还是过时模式时，询问用户而非猜测。
• 利用 @ant-design/cli — 使用 antd migrate、antd lint、antd info 进行 antd 特定检查；不要凭记忆猜测 API。
• 清理 — 始终删除临时克隆目录。