Ant Design Pro 项目升级实战指南模板 diff、智能合并与 antd 迁移检查【免费下载链接】ant-design-pro Use Ant Design like a Pro!项目地址: https://gitcode.com/gh_mirrors/an/ant-design-pro本文是一份面向 Ant Design Pro 开发者的可执行升级手册完整梳理了官方pro-upgrade技能.claude/skills/pro-upgrade/SKILL.md所定义的升级流程拉取最新官方模板、对框架文件做 diff、按「保守合并」原则保留业务代码并通过npx antd系列命令完成 antd 版本迁移专项检查。读完本文你将掌握一套不依赖固定版本号、可反复使用的 Pro 项目升级方法论并能在升级后完成构建验证、变更分类汇总与收尾清理。升级思路概述Ant Design Pro 项目由两类性质截然不同的文件组成一类是 Pro/框架「拥有」的配置与运行时文件升级时应当向官方模板看齐另一类是开发者自己编写的页面与组件升级时必须原样保留。pro-upgrade技能的核心思路是以官方最新模板为基准做差异对比diff再按规则智能合并——框架文件采纳模板结构、保留用户定制业务文件只做最小改动更新导入路径、替换废弃 API绝不重写业务逻辑。这套方法天然支持跨大版本升级例如从 Umi 3 迁到 Umi 4 /umijs/max或 antd 跨大版本迁移因为它不依赖任何硬编码的版本号完全以「模板当前内容」作为唯一参照物。一、升级前准备Preflight动手之前必须先确认仓库工作区状态用户已提交commit或暂存stash所有改动git status应为干净状态或用户明确确认可以继续若工作区不干净应提醒用户先提交或暂存改动——升级过程会修改多个文件随后等待用户确认。这一步看似简单却是整个升级流程的「安全阀」一旦合并过程出错干净的工作区可以随时回退避免业务代码被框架升级连带污染。二、升级全流程总览pro-upgrade把整个升级过程划分为 7 个明确步骤每一步都有对应的操作和产出步骤名称核心动作Step 1拉取最新模板克隆官方模板仓库到临时目录确认其版本Step 2文件分类将项目文件划分为「框架文件」与「业务文件」Step 3框架文件 diff逐一对比用户版本与模板版本的差异Step 4智能合并按规则合并差异业务代码最小改动Step 5antd 专项迁移检查用npx antd系列命令扫描废弃 APIStep 6安装与验证npm install、npm run lint、npm run buildStep 7清理与总结删除临时克隆目录输出分类变更总结下文按步骤逐一展开。三、Step 1拉取最新官方模板首先克隆官方模板到临时目录以下命令以本仓库镜像地址为例实际使用时克隆最新官方模板仓库即可rm -rf /tmp/ant-design-pro-upgrade git clone --depth1 https://gitcode.com/gh_mirrors/an/ant-design-pro.git /tmp/ant-design-pro-upgrade使用--depth1只拉取最新提交避免克隆完整历史导致的时间和磁盘开销。克隆完成后读取模板的package.json确认其版本号——例如当前仓库 package.json 的版本为6.0.3依赖umijs/max ^4.7.3、antd ^6.6.0、ant-design/pro-components ^3.1.14-2、react ^19.2.7且要求 Node.js22.0.0。这些信息将作为后续 diff 与迁移的目标基线。四、Step 2文件分类——框架文件与业务文件升级合并的第一原则是分清「谁的文件」框架文件由 Pro 官方维护、很少被用户定制业务文件由用户编写、必须保留。框架文件需与模板 diff路径说明package.json仅对比 dependencies、scripts、devDependenciesconfig/config.ts框架配置Umi/Max 配置config/routes.ts只对比结构保留用户新增的路由config/defaultSettings.ts布局/主题默认值config/proxy.ts只对比结构保留用户的代理目标src/app.tsx运行时配置initialState、layout、request 等src/access.ts权限定义src/global.tsx全局副作用src/loading.tsx加载组件src/requestErrorConfig.ts请求拦截器/错误处理src/typings.d.ts全局类型声明tsconfig.jsonTypeScript 配置biome.json或biome.jsoncLinter 配置.husky/Git Hookscommitlint.config.*提交信息规范配置src/services/ant-design-pro/自动生成代码禁止手动编辑升级后用npm run openapi重新生成业务文件需保留仅按需调整导入与 APIsrc/pages/**—— 用户页面src/components/**—— 用户组件src/models/**—— 用户数据模型src/services/**/*.ts—— 自定义服务文件不包含ant-design-pro/子目录src/locales/**—— 用户翻译文案框架 key 可能需要更新src/utils/**—— 用户工具函数mock/**—— 用户 Mock 数据以及其他未在上方列出的所有文件结合本仓库的实例印证以当前仓库为例各框架文件的「形态」一目了然config/config.ts 是典型的 Umi/Max 聚合配置包含routes、proxy、layout、locale、request、access、antd、openAPI、tailwindcss等插件配置块升级 diff 时应关注新增/变化的配置项如hash、publicPath、define中的环境变量注入src/app.tsx 承担运行时三件套getInitialState拉取用户信息与默认设置、layout返回 ProLayout 运行时配置菜单渲染、头像下拉、onPageChange登录跳转、SettingDrawer等、request统一网络请求配置src/access.ts 定义了最朴素的权限模型canAdmin依赖initialState.currentUser.access adminsrc/requestErrorConfig.ts 提供了完整的错误处理方案errorThrower抛出自制BizErrorerrorHandler按showType分发到 message/notification/重定向src/global.tsx 仅保留全局副作用引入tailwind.csssrc/loading.tsx 用 antdSkeleton实现页面级加载态src/typings.d.ts 声明了*.css、*.md、mockjs等模块类型以及__APP_VERSION__等全局常量tsconfig.json 定义了/*、/*、root/*等路径别名——升级时若模板调整了别名或编译目标需要同步biome.json 声明了 lint/formatter 规则与忽略目录src/services、mock、dist等。对照此表你就能在自己的项目里快速完成同样的分类。五、Step 3框架文件 diff 要点对每个框架文件需要同时读取用户版本与模板版本重点识别以下四类差异package.json中的新增依赖与版本升级例如本仓库依赖中新增了ant-design/x、tanstack/react-query、tailwindcss等旧项目往往缺少这些依赖或版本落后config/下新增或变化的配置项如插件启停、antd插件的configProvider主题配置、openAPI的schemaPath等导入路径变化典型的如from umi→from umijs/max这是 Umi 4/Max 迁移中最常见的改动点src/app.tsx、src/access.ts等运行时文件的 API 变化例如getInitialState的返回值结构、layout回调的参数签名模板存在但用户项目缺失的新文件例如新增的src/global.tsx、tailwind.css、biome.json等。diff 过程中建议同步查看模板的 config/routes.ts 与 config/proxy.ts 的「结构」routes 关注框架页面如/user/login、/welcome、/admin的access: canAdmin用法的演化proxy 关注按UMI_ENVtest/pre区分代理目标的写法。六、Step 4智能合并策略合并是升级的核心环节pro-upgrade给出了三条明确规则框架文件采纳模板结构、保留用户定制package.json将依赖版本更新到与模板一致同时保留用户额外添加的依赖如果某个依赖存在于用户项目但不在模板中默认视为用户定制并予以保留config/routes.ts框架页面的路由结构跟随模板但用户新增的路由必须原样保留config/proxy.ts结构跟随模板保留用户的代理目标其他框架文件采用模板版本同时保留用户明显的定制内容注释、额外导出、混入的业务逻辑。业务文件只做最小改动若框架模块移动更新导入路径例如umi→umijs/max若模板展示了新的 API 模式替换废弃 API 调用绝不重写业务逻辑、重构组件或改变样式方案除非旧方案已无法工作。自动生成文件禁止手动编辑src/services/ant-design-pro/由 OpenAPI 插件自动生成本仓库对应 src/services/ant-design-pro/api.ts升级后应告知用户运行npm run openapi重新生成而不是手工修改。原则延伸从本仓库的 src/app.tsx 可以看出request.baseURL在开发环境为空、生产环境指向远端 APIerrorConfig通过展开运算符合入——这类「框架骨架 用户定制」的形态正是合并时要小心保护的部分。七、Step 5antd 专项迁移检查antd API 的变化无法靠记忆覆盖官方推荐直接使用ant-design/cli本仓库以ant-design/cli ^6.6.0作为 devDependency 提供配套技能见 .claude/skills/antd/SKILL.mdnpx antd env --format json npx antd lint ./src --format json --only deprecatedantd env输出当前环境的 antd 版本与元数据antd lint扫描src下已被标记为 deprecated 的 API 用法。如果用户正在跨 antd 大版本升级还需要额外运行npx antd migrate current_major target_major --format json其中current_major从用户项目的package.json读取target_major从模板的package.json读取。例如从 antd 5 迁移到 antd 6当前仓库即使用antd ^6.6.0则执行npx antd migrate 5 6 --format json。扫描到的问题需要逐一修复不确定某个组件的当前 API 时用npx antd info Component查询例如npx antd info Button --format json不要凭记忆猜测 API。八、Step 6安装依赖与验证合并完成后执行标准验证链路npm install npm run lint npm run build在本仓库中package.json 的脚本定义明确展示了这套链路lintbiome linttsc --noEmit即类型检查buildmax build。若 lint 或 build 报错按以下常见问题排查API 变更导致的类型错误用npx antd info Component查询最新 API 并修正用法Biome 配置变化带来的新 lint 规则运行npm run biome对应biome check --write自动修复缺失的 peer dependency检查npm install的警告输出并补齐。九、Step 7清理与变更总结验证通过后清理临时目录rm -rf /tmp/ant-design-pro-upgrade随后输出按类别分组的变更总结依赖更新——列出版本变化明细配置变更——说明config/文件的变化代码模式迁移——导入路径变化、API 更新点新增文件——模板中有而用户项目原本没有的文件需人工复核项——任何不确定或需要用户操作的内容。最后提醒用户三件事若使用自动生成的 API 服务运行npm run openapi重新生成全面测试应用提交本次升级的变更。十、升级的核心理念pro-upgrade之所以能稳定复用于任意版本差距的项目源于五条关键原则不硬编码版本——无论用户项目与最新模板之间隔了多少个版本流程都以模板当前内容为基准天然兼容保护业务代码——只为框架兼容性做必要修改业务逻辑与样式方案保持不变保守合并——无法判断某处改动是用户定制还是过时模式时询问用户而非擅自猜测善用ant-design/cli——antd migrate、antd lint、antd info覆盖 antd 专项检查避免凭记忆写 API及时清理——升级完成后删除临时克隆目录不留垃圾文件。这套方法论与仓库中的真实代码互为印证框架文件config/config.ts、src/app.tsx、src/access.ts、src/requestErrorConfig.ts 等与业务文件src/pages 下的页面、组件、Mock的边界清晰可辨读者完全可以参照本文在自己的 Pro 项目中执行一次完整的升级演练。【免费下载链接】ant-design-pro Use Ant Design like a Pro!项目地址: https://gitcode.com/gh_mirrors/an/ant-design-pro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考