企业官网建设流程全解析

Umi MPA 多页面模式怎么配：入口、模板与页面级配置速查指南

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi

Umi 的 MPA（多页面应用）模式会扫描pages目录，把每个子文件夹里的index文件当作独立入口，各自产出一个 HTML，没有前端路由和 history。它适合 H5、插件页、静态导出的多页面站点。读完这篇，你能按目录约定搭出最小工程，理解config.json、入口导出配置、mpa全局配置三层的优先级，并在入口不生效、模板不替换时快速定位问题。

先判断：MPA 模式适合你的场景吗

注意一个容易混淆的点：Umi 4 的 MPA 是"真 MPA"，和 Umi 3 模拟路由的方案完全不同。从 Umi 3 迁过来的项目，先确认行为差异再套用旧配置。

最短上手路径：三步跑通第一个多页面工程

不需要一开始配完整，先跑通最小例子。

1. 打开 MPA 开关。在项目的config.ts（或.umirc.ts）里加一个mpa配置对象，值留空即可：

   export default { mpa: {}, };

   这一步成功的标志：启动或构建后，控制台不再输出路由表，而是按入口逐个处理。

2. 按约定放入口文件。在pages/下建一个文件夹，里面放index.tsx，默认导出一个 React 组件即可，不用自己写ReactDOM.render：

   pages/ ├── foo/index.tsx └── bar/index.tsx

   组件只需export default function Page() { ... }。默认走 React 18 渲染；要 17 的行为，装 17 版本的 react 和 react-dom，框架会自己适配。

3. 跑一次构建确认产物。执行最短命令：

   umi build

   这一步成功的标志：输出目录里出现foo.html和bar.html，文件名与文件夹名一一对应，且 HTML 里能看到页面内容。

想直接抄作业的话，仓库里examples/mpa/就是一个完整的最小工程，目录布局和上面完全一致。

关键配置心智模型：三层配置谁说了算

配置分三层，理解"从哪读"比记住字段更重要：

页面级配置有两个来源，别混着用：

• 文件式：入口同级放config.json，写title、layout等字段。examples/mpa/pages/foo/config.json里就只配了一个 title。
• 导出式：开启getConfigFromEntryFile后，直接在index.tsx里export const config，examples/mpa/pages/foo/index.tsx同时演示了导出 title 和 layout 的写法。

一个最小片段说明导出式解决什么问题——让页面自己声明布局，不用回全局配置里翻：

export const config = { title: 'foo 页面', layout: '@/layouts/foo', };

模板机制一句话：全局template兜底，页面级template覆盖。想给某个页面换整套 HTML 骨架，就在它的配置里指一个新模板文件，模板语法沿用 lodash template 写法。

高频问题诊断：按这个顺序查

1. 入口没被识别，构建产物里缺页面

• 现象：某个文件夹明明有页面，产物里却没有对应的 html。
• 优先检查：文件是否严格叫index.tsx（或.tsx/.jsx/.ts/.js），且直接位于pages/的一级子文件夹里。像pages/hoo.tsx这种散落在根下的单文件不会成为入口。
• 快速动作：把文件挪进pages/新目录/index.tsx结构。
• 成功标志：重新构建后出现以文件夹命名的 html。

2. 模板变量没替换，页面空白

• 现象：打开产物 html，标题是空的，或内容挂在空 body 上。
• 优先检查：模板里是否同时保留了<%= title %>和<%= mountElementId %>两个变量占位。
• 快速动作：对照examples/mpa/templates/default.html补回缺失变量。
• 成功标志：页面能渲染出组件，且 title 显示为配置值而不是目录名。

3. 页面级 layout / title 没生效

• 现象：改了config.json，刷新后布局还是默认的。
• 优先检查：如果配置写在入口文件的export const config里，先确认全局配置开了getConfigFromEntryFile，否则只认config.json。
• 快速动作：两种写法只保留一种，路径统一用@/别名。
• 成功标志：不同入口呈现各自配置的标题与布局。

4. 入口扫描不到代码，构建报错找不到文件

• 现象：把业务代码放在非默认根目录（比如 Electron 项目的src/webview），构建直接找不到页面。
• 优先检查：APP_ROOT是否指向了真实的应用根目录。examples/mpa-with-app-root-and-alias/的脚本里就是用APP_ROOT=src/webview umi dev解决的。
• 快速动作：在启动/构建脚本前缀设置APP_ROOT，并把pages、layouts、templates都放进这个根目录。
• 成功标志：构建产物里包含该根目录下所有入口的 html。

5. 本地启动慢，怀疑配置拖累

• 现象：页面很多时 dev 启动明显变慢。
• 优先检查：是否所有入口都在参与构建。
• 快速动作：在.env里写MPA_FILTER=foo,bar，只启动当前要改的页面。
• 成功标志：启动日志只出现被筛选的入口，且调试完成记得删掉或改成构建值。

发布前必须核对的 6 项

• 每个页面都是pages/${目录}/index.tsx结构，没有散落的单文件
• 每个入口的标题来源唯一：config.json、导出 config、mpa.entry三选其一，没有互相覆盖
• 模板同时包含title与mountElementId变量
• 所有layout路径以@/开头且指向存在的文件
• 构建环境的APP_ROOT、MPA_FILTER与本地开发值已区分，没有把筛选值带上线
• 跑一次完整构建，逐一打开产物 html 抽查标题、布局、挂载点

延伸资料与路径

仓库内的真实参考，按顺序看：

1. 官方指南（配置项与约定原文）：docs/docs/docs/guides/mpa.md
2. 最小 MPA 工程（含config.json、导出式 config、默认模板、两套布局）：examples/mpa/
3. 自定义应用根目录与别名场景：examples/mpa-with-app-root-and-alias/

【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi