企业官网建设流程全解析

学习 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 一起发布。我整理了一张表，把这些差异直接摆出来：

单看这张表，你可能会觉得"那直接用 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 -v

V4 时代，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 Classic（1.x）和 Yarn Berry（2.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 yarn@latest盲追新版，不少框架对 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 --path=src/pages/Demo/List

--path表示把区块文件放在项目的哪个目录下。这里我先泼一盆冷水：这个命令在公司网络内有时会因为区块仓库的源不稳定而失败。我在实际学习中发现，更稳定的是第二种姿势——直接从官方 pro-blocks 源码仓库拉下来，手动拷贝。

3.4 手动接所有 Block 的通用做法

如果你要把全部官方 Block 都接到一个 V4 项目里，我建议这样操作：

1. 克隆 pro-blocks 源码仓库到本地。
2. 打开仓库，找到blocks目录，里面按功能分组，有List、Form、Profile、Result、Exception、Account等。
3. 把需要的区块目录，一个个复制到src/pages下面对应的路径。
4. 每个区块一般自带index.tsx、service.ts、mock数据和局部样式。复制完，还要看它的_mock.ts有没有覆盖到项目根目录的mock配置里。
5. 检查路由文件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 start

UmiJS 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.tsx

V4 时代，路由配置全部挤在config/config.ts里；V5 开始支持config/routes.ts拆分，每个页面模块的路由可以单独管理。如果你是迁移项目，这一步是改动最大的地方之一。

4.3 V5 里怎么"含所有 Block"

V5 本质上废除了类似umi block add这样的独立区块命令，官方更希望你用组件组合的方式来做页面。也就是说，它换了一种思路：不是把"一整块页面代码"搬过来，而是把ProTable、ProForm、ProLayout、ProCard这些组件拼起来，形成一个"新区块"。

那标题里"含所有 Block"在 V5 里怎么落地？我的做法是：

1. 创建项目时选择"生成所有示例页面"，让脚手架自动把 Dashboard、List、Form、Profile 等全部铺到src/pages。
2. 官方 pro-blocks 仓库依然存在，里面的区块文件拿到 V5 项目里，大部分能直接用，但要注意 import 的组件路径变了。比如老的@ant-design/pro-table在 V5 里对应的版本是 2.x。
3. 手动复制区块后，路由配置改到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.ts，V5 里改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 --port=8001

但注意，如果你用.env文件设了端口，命令行参数可能被覆盖。这种情况去.env里改PORT=8001是最直接的。

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-size=4096" yarn build

这个在我实践中是有效的。Windows 下环境变量的写法不同，要先把NODE_OPTIONS用set设好再执行 build。

7. 这个系列接下来我打算记录什么

安装只是万里长征第一步。这一篇学完，V4、V5 的环境差异、脚手架命令、Block 接入路径都记录在案了。下一步我会深入到具体的页面开发实践，比如用 ProTable 改造一个自定义列表、把 ProForm 和 Modal 组合成弹窗表单、理解initialState与登录态的关系。这些是真正工作中每天要碰的东西，也是"装好之后能干活"的下一个分水岭。

我个人的体会是：ADP 安装永远不难，难的是安装之后你还记不记得它帮你做了什么。第一次装完，你可能会被满屏的目录感动；但真到了自己写业务，遇到"加一个页面要不要复制整个 Block"这种问题时，前面这些底层认知才会真正起作用。