企业官网建设流程全解析

UmiJS MPA 配置全解：5 个关键点从零到跑通

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

Umi 的 MPA 模式把src/pages下每个页面独立打包成一个 HTML 文件，无路由、无 history，适合 H5 和插件研发场景。看完这篇，UmiJS MPA 配置从建目录到构建产物你都能自己搞定。

H2 一：30 秒看懂核心概念

先分清三个概念，后面就不会晕：

一句话记住：MPA 下没有umi.js，每个入口文件就是一个 webpack entry。

顺带一提，Umi 3 的 MPA 是 Mock 了路由渲染，和 Umi 4 的实现不同，升级时别直接照搬旧配置。

H2 二：从零到跑通（最小可运行路径）

以官方示例 examples/mpa/ 为参照，三步跑通：

Step 1建页面入口

// src/pages/foo/index.tsx export default () => <div>Hello Foo</div>

导出 React 组件就行，框架会自动渲染，不用自己写ReactDOM.render。

Step 2开启 mpa

// .umirc.ts export default { mpa: {}, };

mpa 是内置功能，配置即开启，空对象也能跑。

Step 3启动与构建

npm run dev npm run build

build 后每个入口对应一个 HTML，foo、bar两个目录就产出foo.html和bar.html。

H2 三：高频报错速查

新手最常撞的五个坑，对号入座：

H2 四：按场景挑进阶用法

场景一：自定义 HTML 模板（UmiJS MPA 模板不生效怎么排查）

全局或页面级都可以指定template：

// pages/foo/config.json { "template": "templates/custom.html", "title": "foo" }

模板里至少保留<%= title %>和<%= mountElementId %>两个变量，缺了就是"模板不生效"的常见原因。

场景二：不用 config.json，入口文件直接导配置

// .umirc.ts 中开启 mpa: { getConfigFromEntryFile: true }

// 入口文件里导配置 export const config = { title: 'foo', layout: '@/layouts/foo' }

配置跟代码走，改页面不用翻 JSON。

场景三：按需启动提速

在.env里写MPA_FILTER=bar,foo，只启动这两个页面，页面多时构建速度明显提升。

场景四：APP_ROOT 改目录的正确姿势

源码不放在项目根目录（典型如 Electron 渲染进程）时：

APP_ROOT=src/webview umi dev

参考 examples/mpa-with-app-root-and-alias/，把入口指到src/webview，别名照常可用。

💡 配置优先级：页面级 config.json / 入口导出 >.umirc.ts的mpa.entry全局配置。

H2 五：上线前自检清单

收个尾，上线前过一遍：

• .umirc.ts 已开启 mpa
• 确认 pages/[name]/index.tsx 存在
• 模板含 title 与 mountElementId 变量
• 各页面 title、layout 已单独配置
• 构建产物每页对应一个 HTML
• MPA_FILTER 未误删页面

完整细节以官方文档为准：docs/docs/docs/guides/mpa.md，更多页面写法看 examples/mpa/。

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