学习 Ant Design Pro 4 和 5我把整个安装过程、版本差异、Block 体系串了一遍。这篇是系列第一篇重点解决怎么用 Yarn 把 ADP V4/V5 完整跑起来并且把官方那些 Block 全部接到项目里的问题。我自己是在给团队做中后台脚手架选型时开始接触当时手头既有旧项目跑在 V4 上又有一个新项目打算用 V5索性把两代的安装逻辑都摸了一遍。如果你也打算从零搭一个 React 中后台项目或者正被同一个技术栈两个版本怎么迁移搞得头大这篇记录应该能省你不少时间。先说结论Ant Design Pro 从来不是一个普通的轮子它更像一套中后台工程的完整样板间。V4 和 V5 表面看只是版本号变了实际上从构建工具到 React 版本再到组件生态底层都换了一代。所以标题里V4 V5不是随便写的你得先搞清楚自己该装哪个再决定用哪条命令。下面我按自己操作的顺序把环境准备、两代安装、Block 接入、踩坑记录全部展开。1. 先搞明白 V4 和 V5 到底差在哪再决定装哪个很多初学者上来就执行安装命令结果装完发现页面长得不一样、目录结构也对不上最后只能删掉重来。我建议大家先花十分钟看版本差异这不是浪费时间是在给后面的安装扫雷。1.1 两代 ADP 的技术底座对比Ant Design Pro V4 是 UmiJS 3 时代的产物V5 则跟随 UmiJS 4 一起发布。我整理了一张表把这些差异直接摆出来对比项ADP V4ADP V5底层框架UmiJS 3UmiJS 4 / umijs/maxReact 版本React 16/17React 18组件库Ant Design 4.xAnt Design 5.xPro 系组件ProComponents 1.xProComponents 2.x配置方式config/config.ts 或 .umirc.ts推荐 config/routes.ts 拆分路由创建命令yarn create umiyarn create ant-design/pro区块Block能力有独立 CLI 和插件生态收敛为核心能力需手动组织数据流示例DVA Models 为主内置并支持更多请求方案单看这张表你可能会觉得那直接用 V5 不就行了V4 还有什么好学的。但实际项目里V4 存量特别多尤其是一些大型企业中后台系统它们不会因为 V5 出了就立刻迁移。更现实的情况是你接手了一个 V4 项目同时公司新开了一个 V5 项目。1.2 包含所有 Block的真实含义标题里含所有 Block是一个很关键的表述。在 UmiJS 的语境里Block 不是区块链而是区块——你可以把它理解成一个个已经做好的页面模板列表页、表单页、详情页、结果页、异常页、个人中心页等等。官方脚手架创建项目时通常会问你要不要把全部示例页面生成进来。这个问题我一直在实际学习中发现很多中文教程会直接把含所有 Block翻译成安装所有模块然后让人用一条装某插件的命令去补齐。其实更稳妥的做法是在创建项目的那一步就选择包含所有页面的完整模板。V4 里对应Ant Design Pro完整模板而不是pro-simple精简模板V5 里同样有是否生成全部页面的交互选项。理解了这一步后面就不容易跑偏。1.3 版本选择的实际建议我个人给团队的建议是这样的如果项目是全新立项且团队对 React 18 生态没有顾虑直接上 V5。如果要维护老系统或者项目里其他依赖还停留在 React 16 时代老老实实用 V4。如果只是个人学习两个版本都装一遍因为好多人将来是要做迁移的只看文档远不如亲手跑一遍两代脚手架体会更深。确定了版本接下来就要碰环境了。这一步坑最多但恰恰又是大家最喜欢跳过的一步。2. 环境准备Yarn 版本和 Node 版本决定安装成败安装 ADP 说到底是装一个复杂的 Node 工程环境的干净程度直接决定你之后的每一步是否顺利。我见过太多人上来就报错追到最后发现是 Node 版本太老或者 Yarn 版本太新。2.1 Node 版本V4 和 V5 的要求不一样先看一下我自己机器上的操作。node -vV4 时代UmiJS 3 对 Node 的要求是 10.13 以上但真正跑起来Node 12 之前会有各种兼容报警。V5 的 UmiJS 4 则要求 Node 14 以上官方更推荐 Node 16/18。所以如果你还在用 Node 10 或 12装 V5 大概率会直接失败。我习惯用 nvm 这类版本管理工具切 Node而不是一股脑装个全局最新版。最新版 Node 不一定就是最兼容的尤其是面对老项目时Node 18 有时候会在安装某些原生依赖时闹脾气。2.2 Yarn 版本这里最容易翻车用 Yarn 安装听起来很简单但 Yarn 自己也分成了两个大时代Yarn Classic1.x和 Yarn Berry2.x/3.x。UmiJS 3 和 4 官方文档里给的命令基本都是基于 Yarn Classic 的习惯写法的。比如yarn create umi这种命令在 Yarn 2 里的行为会变甚至在交互式命令行工具里会弹不出选项。所以我的建议是corepack disable npm install -g yarn yarn -v如果你的机器之前开过 Corepack把 Node 里自带的那套 Yarn 管理关掉再去装一个全局稳定的 yarn 1.22.x。这样yarn create、yarn add这些命令的交互风格才是我们下面要演示的。注意不要用npm install -g yarnlatest盲追新版不少框架对 Yarn Berry 的 PnP 模式还没完全适配装出来的 node_modules 结构都是异形后面配 webpack、配 less、配 Mock 都会莫名奇怪。2.3 配置镜像源不该成为玄学在国内网络环境下直接连默认的 npm registry装 Ant Design 这种依赖量极大的项目等到天荒地老是常态。这一步我建议先改镜像源但注意看下文镜像只是一个加速手段跟任何全局代理无关纯粹是网络基础设施的选择。yarn config set registry https://registry.npmmirror.com yarn config get registry设置之后装包会快很多尤其是 electron、node-sass 这类带二进制文件的老依赖镜像还会帮忙处理二进制镜像省掉很多编译问题。2.4 提前检查磁盘和端口Ant Design Pro 完整模板装完依赖node_modules 轻轻松松上 600MB构建临时文件也要几百 MB。磁盘不够的人会有体会装到一半报ENOSPC前面所有功夫都白费。端口方面ADP 默认开发端口是 8000。建议提前看一下 8000 被谁占用了lsof -i :8000如果被占用要么先杀掉相关进程要么记住后面的--port参数。下面讲安装的时候我会再提到这个。3. 用 Yarn 安装 ADP V4完整模板一路跑通环境准备就绪后我们开始装 V4。这里我会把每一步的交互选择、命令输出验证都写清楚确保照着做能复现。3.1 创建项目并选择完整模板在你要放置项目的目录下执行yarn create umi demo-adp-v4这里yarn create umi等价于yarn create umi拿到 umi 脚手架包。执行之后CLI 会进入交互式询问。不同版本脚手架选项长得不太一样但核心是让你选择项目类型。在选项列表里找到Ant Design Pro这一项它对应的是完整模板会把仪表盘、列表、表单、详情、结果、异常、账户等页面全部生成。如果你选的只是一个简单基础模板那后面就得手动补一堆页面那就违背了含所有 Block的初衷。3.2 安装依赖并启动进入项目目录执行安装cd demo-adp-v4 yarn这一步会把 UmiJS 3、Ant Design 4.x、ProComponents、DVA、Mock 等几十个核心依赖全拉下来。yarn命令不带子命令默认就是安装。等它跑完你会看到 success 提示。启动开发服务器yarn start正常情况终端会有编译进度条完成后访问http://localhost:8000/。看到首页出现分析页、工作台页说明基础安装已经成功。验证一下构建流程能不能过yarn build构建完成之后项目中会多出一个dist目录。这一步很重要因为它会把很多运行时的问题提前暴露出来。我建议所有人在安装完的第一时间就构建一次不管后面是不是要用到生产包。3.3 给 V4 添加 Block 的两种姿势V4 的 Block 机制比较外挂式。最早的方案是装umi-plugin-block插件然后在 UmiJS 配置里开启。完整步骤大概是下面这几行yarn add -D umi-plugin-block然后在你使用的配置文件里config/config.ts或.umirc.ts加入import { defineConfig } from umi; export default defineConfig({ blocks: { // 默认去官方区块仓库匹配 enable: true, }, });之后尝试列出可用区块yarn umi block list如果环境正常它会展示一批官方区块名比如BasicList、AdvancedList、BasicForm、StepForm、AdvancedProfile、BasicProfile等等。添加某个区块到项目里用的命令是yarn umi block add BasicList --pathsrc/pages/Demo/List--path表示把区块文件放在项目的哪个目录下。这里我先泼一盆冷水这个命令在公司网络内有时会因为区块仓库的源不稳定而失败。我在实际学习中发现更稳定的是第二种姿势——直接从官方 pro-blocks 源码仓库拉下来手动拷贝。3.4 手动接所有 Block 的通用做法如果你要把全部官方 Block 都接到一个 V4 项目里我建议这样操作克隆 pro-blocks 源码仓库到本地。打开仓库找到blocks目录里面按功能分组有List、Form、Profile、Result、Exception、Account等。把需要的区块目录一个个复制到src/pages下面对应的路径。每个区块一般自带index.tsx、service.ts、mock数据和局部样式。复制完还要看它的_mock.ts有没有覆盖到项目根目录的mock配置里。检查路由文件config/config.ts中的routes配置把新增区块对应的路由补上。举个例子新增了一个名叫HireList的区块放到src/pages/Hire/List后路由里要加{ name: hire-list, icon: TableOutlined, path: /hire/list, component: ./Hire/List, },不加这段配置页面文件躺在磁盘上但浏览器访问不了。提示手动接 Block 最大的好处是不依赖 CLI 网络状态而且你能亲眼看到每个区块由哪些文件构成。第一次做的时候可能觉得麻烦但你对项目的掌控力会比纯命令高一个 level。4. 用 Yarn 安装 ADP V5新一代脚手架体验V5 的创建方式和 V4 差异很大官方把命令收敛成了yarn create ant-design/pro这一步走完得到的项目直接就是完整的 Pro 工程。4.1 创建项目并处理交互选项yarn create ant-design/pro demo-adp-v5执行后它会问几个问题我记得比较关键的有是否使用 TypeScript。是否生成所有示例页面。选择基础框架是 UmiJS 4 还是 umijs/max。是否需要内置权限、国际化、Mock 等能力。我建议第一次学习都选是、选完整。目的就是先看到它能给的全貌后面再一个个拆掉不需要的东西比一开始就精简更容易理解。进入目录cd demo-adp-v5 yarn依赖装完后启动命令我用的是yarn startUmiJS 4 的编译速度比 UmiJS 3 快不少因为它做了不少缓存和并行化的改进。默认访问http://localhost:8000/能看到新版首页。4.2 观察 V5 目录结构的变化装完之后我第一件事是看目录tree -L 2 -d会看到src下的结构大概是这样src/ ├── components/ ├── pages/ │ ├── Dashboard/ │ ├── List/ │ ├── Form/ │ ├── Profile/ │ ├── Result/ │ ├── Exception/ │ └── Account/ ├── services/ ├── locales/ ├── access.ts ├── app.tsx └── global.tsxV4 时代路由配置全部挤在config/config.ts里V5 开始支持config/routes.ts拆分每个页面模块的路由可以单独管理。如果你是迁移项目这一步是改动最大的地方之一。4.3 V5 里怎么含所有 BlockV5 本质上废除了类似umi block add这样的独立区块命令官方更希望你用组件组合的方式来做页面。也就是说它换了一种思路不是把一整块页面代码搬过来而是把ProTable、ProForm、ProLayout、ProCard这些组件拼起来形成一个新区块。那标题里含所有 Block在 V5 里怎么落地我的做法是创建项目时选择生成所有示例页面让脚手架自动把 Dashboard、List、Form、Profile 等全部铺到src/pages。官方 pro-blocks 仓库依然存在里面的区块文件拿到 V5 项目里大部分能直接用但要注意 import 的组件路径变了。比如老的ant-design/pro-table在 V5 里对应的版本是 2.x。手动复制区块后路由配置改到config/routes.ts中。拿列表页举例。V5 的src/pages/List下会有TableList代码里核心是ProTable它把查询表单、工具栏、分页、操作列都收拢在了一个组件里。想基于它扩展连 Block 都不需要直接改 columns 配置和 request 方法即可。4.4 验证 V5 工程是否真的完整安装不是等终端出现 success 就完事。我每次都会做下面几件事来验证看src/pages下是不是有超过 15 个页面目录。看config/routes.ts里是不是有足够多的路由记录。执行一次yarn build确认生产构建能过。切换上海、英文两种语言看国际化是否生效。模拟一个无权限账号登录看 403 页面是否正常显示。以上任何一步出问题都说明某个 Block 或配置没有完整接入这时候回到目录和路由配置里排查比瞎猜更快。5. 深入 Block 里层页面、路由、权限、服务四件事很多人以为装好 Block 就万事大吉其实只是把文件摆上去了。真正让它成为工程的一部分后面四件事一个都不能少。5.1 页面文件只解决长什么样Block 的index.tsx解决的是 UI 展示表格列、表单字段、详情描述、按钮事件都在这里。它由 Ant Design 和 ProComponents 的组件拼出来。单独打开它你会发现它无非就是 JSX 加 hooks。5.2 路由配置解决能不能访问页面文件放对了路由没配浏览器就是 404。V4 里你要改config/config.tsV5 里改config/routes.ts。路由的name字段还会自动映射到菜单上这一层不搞清楚Block 永远只是文件尸体。5.3 权限和 access 控制决定给谁看ADP 的权限模式和路由是联动的。项目里一般有src/access.ts里面定义了当前用户能访问哪些路由。比如export default function access(initialState) { const { currentUser } initialState || {}; return { canAdmin: currentUser currentUser.access admin, }; }然后在路由里面通过access字段绑定{ path: /admin, component: ./Admin, access: canAdmin, }接入 Block 时要看它的页面上有没有用到currentUser或useAccess。如果用到而你不配置权限轻则页面空白重则直接跳转 403。5.4 service 和 mock 决定数据从哪来Block 里那些表格、表单、详情大多数有抽出来的 service 请求。V4 里常见的是service.ts里导出fetchXxxList方法V5 里类似。而开发环境下数据一般来自mock文件夹。手动接入新 Block 时经常犯的一个错是只复制了index.tsx忘了把关联的 service 和 mock 一起搬过来。结果页面能打开表格一直转圈。我建议接任何区块时先看它引用了哪些相对路径文件一起复制再全局搜索是否有遗漏。6. 学习路上最值得记下的一批坑这部分是我反复安装两代 ADP 之后沉淀下来的问题每一个都是真实遇到过的按发生率排序。6.1 高版本的 Node 反而不兼容Node 20 刚出那会儿我特意拿来跑 V4。结果启动是能启动但编译时总报某个依赖不支持最后又切回 Node 14 才能稳定跑。V4 这种老工程追求新版本 Node 没有任何意义V5 则建议 Node 16 或 18太老的 Node 也会在yarn create ant-design/pro阶段报错。6.2 Yarn Berry 的交互式命令失灵如果你开着 Corepack执行yarn create umi时yarn 会默认用 Yarn Berry 的协议去解析包交互式选择界面可能压根不弹出来直接卡死在输出。这时关闭 Corepack、回到 Yarn Classic问题立刻消失。6.3 端口 8000 被占用这个太常见了。换端口启动可以用yarn start --port8001但注意如果你用.env文件设了端口命令行参数可能被覆盖。这种情况去.env里改PORT8001是最直接的。6.4 node_modules 损坏后的还原手段依赖装到一半网络断了、系统强制关机后面再启动就会出现奇奇怪怪的报错比如Cannot find module xxx。我目前的习惯是rm -rf node_modules yarn cache clean yarn有些时候连yarn.lock都要删掉重新生成。不过在删锁文件之前先看清楚项目是不是锁了版本否则升级了一堆不期望的依赖反而更麻烦。6.5 Mock 不生效V5 里 Mock 默认是按需开启的。如果你发现某个列表页没有数据先检查根目录mock文件夹是否存在、app.tsx或配置文件有没有开启 mock。V4 中有些 Block 自带_mock.ts这个文件要放到项目根目录mock下面才会被扫描到放在页面目录里是没有用的。6.6 Build 期内存溢出完整 Block 全部接入后编译产物会很大老机器用默认内存跑yarn build可能直接报heap out of memory。Umi 系列构建支持设置NODE_OPTIONS--max-old-space-size4096 yarn build这个在我实践中是有效的。Windows 下环境变量的写法不同要先把NODE_OPTIONS用set设好再执行 build。7. 这个系列接下来我打算记录什么安装只是万里长征第一步。这一篇学完V4、V5 的环境差异、脚手架命令、Block 接入路径都记录在案了。下一步我会深入到具体的页面开发实践比如用 ProTable 改造一个自定义列表、把 ProForm 和 Modal 组合成弹窗表单、理解initialState与登录态的关系。这些是真正工作中每天要碰的东西也是装好之后能干活的下一个分水岭。我个人的体会是ADP 安装永远不难难的是安装之后你还记不记得它帮你做了什么。第一次装完你可能会被满屏的目录感动但真到了自己写业务遇到加一个页面要不要复制整个 Block这种问题时前面这些底层认知才会真正起作用。
