尧图网页设计 
三步跑通 UmiJS MPA 多页面应用一份完整实战指南【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi新建一个 UmiJS 多页面应用MPA项目时第一步不是写配置而是把目录摆对。这篇文章带你完整走一遍 UmiJS MPA从最小项目三步跑通到一个页面 一份独立 HTML的机制拆解再到模板、根目录等关键配置项的调优最后是排错对照表和上线前清单照做即可落地。先跑起来最快跑通 MPA 项目的三步先把结论放前面在 Umi 4 中MPA 是内置能力通过配置开启目录摆对之后几乎不用额外代码。第一步把目录摆对下面这棵目录树验证的是 UmiJS MPA 的核心约定pages/下每个子文件夹就是一个页面文件夹里的index.tsx是入口见 examples/mpa/。my-mpa/ ├── .umirc.ts └── src/ ├── layouts/ │ └── basic.tsx └── pages/ ├── home/ │ └── index.tsx └── about/ └── index.tsx文件夹名就是页面名构建后会分别产出home.html和about.html。入口文件里只需导出一个 React 组件ReactDOM.render这些样板代码框架会帮你生成不用自己写。第二步用配置开启 MPA下面的.umirc.ts验证的是怎么让 Umi 进入 MPA 模式——只要出现mpa这个 key内置功能即启用源码里enableBy: api.EnableBy.config见 mpa.ts// .umirc.ts export default { mpa: {}, };第三步跑构建验证产物执行umi dev或umi build启动时控制台会打印一行[MPA] MPA Mode Enabled同样来自 mpa.ts这就是最直接的开关确认信号。构建完成后dist/里应该能看到home.html、about.html每个都是独立的完整 HTML——注意里面没有SPA 模式的umi.js和路由逻辑。三步走完dev server 已经能同时打开两个页面了。接下来花两分钟弄明白多是怎么来的后面调配置才不会玄学。它怎么多起来一个页面 一份独立 HTMLUmi 4 的 MPA 是真 MPA和 Umi 3 的模拟路由方案完全不同官方文档明确提示了两代实现的差异。它的内部流程其实就四步读一遍源码就能对上收集入口扫描src/pages/下的每个子目录找到index.tsx/ts/jsx/js每个目录生成一个 entry生成临时入口为每个页面写一份临时文件内容是import App from 你的页面加一段ReactDOM.createRoot(...).render(...)如果配了 layout 还会把Layout包在外面注册 webpack 入口modifyEntry钩子把 SPA 的umi入口删掉换成 N 个页面入口所以 MPA 产物里没有全局路由 bundle逐页面产 HTML给每个入口挂一个html-webpack-plugin输出页面名.html并把页面配置作为变量注入模板。这套机制解释了两件事。第一MPA 产物没有路由、没有 history页面之间跳转是整页刷新——访问哪个页面服务器就必须能直接吐出对应的.html这也是后面 404 问题的根源。第二文档里也说了MPA 模式下大量面向 SPA 的插件能力不可用它更适合作为构建工具来用所以别指望在 MPA 项目里继续用路由相关的插件。理解了机制下面这些配置项就不再是黑盒了——它们恰好分别作用在收集入口、注入模板、包裹布局这几个环节上。值得动手调的 4 个开关真正改变产物的 UmiJS MPA 配置页面级 config.json让每个页面有自己的标题和布局全局配置管所有页面config.json管单个页面。下面的例子验证的是页面级配置的完整写法title缺省时默认是目录名layout必须以/或绝对路径开头源码里有断言校验template可以让单个页面换模板// src/pages/about/config.json { title: 关于我们, layout: /layouts/basic, template: templates/marketing.html }如果不想每个页面都放一个config.json还有个替代方案在.umirc.ts里设mpa.getConfigFromEntryFile: true然后直接在入口文件里export const config { title: ... }导出配置。examples/mpa/ 用的就是这种方式两种写法选一种即可混用反而容易困惑。HTML 模板从默认模板到多模板切换不配任何模板时框架会用它内置的一份最小模板只有title和挂载点配了mpa.template就从项目根目录按路径找文件——注意路径解析起点是根目录不是src/。模板支持 lodash template 语法可用变量包括title、mountElementId等examples/mpa/templates/default.html 就是现成参照。多模板切换的思路很简单全局定一个默认模板再在特定页面的config.json里用template覆盖。下面这份营销页模板验证的是页面级模板如何拿到页面变量!-- templates/marketing.html -- !DOCTYPE html html head title% title % - 营销活动/title /head body div id% mountElementId %/div /body /html这里有个隐形约束模板里必须保留div id% mountElementId %React 就挂载在这个节点上删了它页面会白屏。layouts 复用一份布局套多个页面布局是套在页面组件外面的壳。全局写mpa.layout: /layouts/basic所有页面都会包上layouts/basic.tsx导出的组件某几个页面想换壳就在各自的config.json或export const config里写layout覆盖全局值。源码里这一步发生在临时入口生成阶段有 layout 就渲染LayoutApp //Layout没有就只渲染App /mpa.ts 的onGenerateFiles钩子。对营销站、文档站这种多数页面共用头部页脚、少数页面例外的结构这套全局 页面级覆盖的粒度正好够用。APP_ROOT 设置把应用根目录挪个位置默认情况下 Umi 以当前工作目录为根src/、.umirc.ts都从这里找。如果你的代码放在子目录里——典型场景是 Electron 混合应用仓库根目录放主进程渲染进程代码单独放在src/webview/——就可以用环境变量APP_ROOT指过去。下面的package.json片段验证了这种用法官方示例 examples/mpa-with-app-root-and-alias/ 里整个pages/、templates/都在src/webview/下{ scripts: { dev: APP_ROOTsrc/webview umi dev } }这个变量的读取逻辑很短就四行取process.env.APP_ROOT是相对路径就拼到当前工作目录下否则直接用没设置就退回当前目录。想确认它生效可以看 packages/umi/src/service/cwd.ts。顺带说清一个常见误解网上老文章里写的umi build --mpa命令行参数在 Umi 4 源码里并不存在——MPA 靠的是上文说的mpa配置项。真正影响构建行为的参数是环境变量MPA_FILTER页面多的项目 dev 启动慢时设MPA_FILTERhome,about就只收集这两个页面启动速度立竿见影mpa.ts 里的filterEntry函数。配置项就调到这儿。接下来把这些坑集中摆出来——出问题时直接对表不用从头翻机制。出问题了对照这张表现象根因处理访问页面 404 或内容错乱MPA 没有路由访问about不等于自动找到about.html服务器没做映射时会落到错误页面让 Web 服务器把路径映射到对应的.html或直接用/about.html访问同时确认页面目录符合pages/页面名/index.tsx约定产物还是 SPA有 umi.jsMPA 没生效.umirc.ts里没写mpa配置或写错了配置文件启动时确认控制台是否打印[MPA] MPA Mode Enabled没打印就是配置没被读到模板不生效改了 HTML 页面没变化mpa.template路径解析起点是项目根目录而非src/路径写不到文件或页面级config.json的template覆盖了全局值先核对路径能否从根目录解析到再查该页面的config.json是否有页面级template页面白屏自定义模板里漏了% mountElementId %挂载节点React 无节点可挂模板 body 中补回div id% mountElementId %/div配置了 layout 却报错/不生效源码断言要求layout必须是字符串且以/或/开头改成layout: /layouts/basic这类写法页面多了 dev 启动特别慢所有页面都作为入口参与构建用.env或命令行设置MPA_FILTERhome,about按需启动改了APP_ROOT但配置、页面全找不到APP_ROOT是相对当前工作目录解析的执行命令的目录不对确认在package.json所在目录执行脚本或改用绝对路径表里 90% 的坑本质都是路径解析起点和约定目录这两件事。对完表、修完问题剩下的就是上线前的例行检查了。从 Demo 到生产上线前检查清单 发布前逐项过一遍比出问题再排查快得多每个页面的title都显式设置了——不设置时会回退成目录名about页标题显示 about 这种事上线后很难看线上 Web 服务器配好了路径 →.html文件的映射SPA 习惯的 history fallback 在 MPA 下帮不了你模板里保留mountElementId挂载点head里的统计、SEO meta 信息按页面核对过不需要路由相关插件——MPA 模式下这些能力本就不可用依赖它们的代码要么删掉要么改写页面数量超过 10 个时本地和 CI 都用MPA_FILTER验证过按需构建的行为如果用了APP_ROOT确认 CI 脚本里环境变量同样传了——本地 dev 正常、线上构建找不到src/几乎都是漏了它构建产物里逐页抽查每个页面一份独立 HTML无umi.jstitle与config.json一致延伸阅读MPA 官方文档docs/docs/docs/guides/mpa.md最小可运行示例examples/mpa/APP_ROOT 实战示例examples/mpa-with-app-root-and-alias/MPA 功能实现源码packages/preset-umi/src/features/mpa/mpa.tsAPP_ROOT 读取逻辑packages/umi/src/service/cwd.ts完整文档站与全部示例入口docs/、examples/【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 三步跑通 UmiJS MPA 多页面应用：一份完整实战指南
三步跑通 UmiJS MPA 多页面应用一份完整实战指南【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi新建一个 UmiJS 多页面应用MPA项目时第一步不是写配置而是把目录摆对。这篇文章带你完整走一遍 UmiJS MPA从最小项目三步跑通到一个页面 一份独立 HTML的机制拆解再到模板、根目录等关键配置项的调优最后是排错对照表和上线前清单照做即可落地。先跑起来最快跑通 MPA 项目的三步先把结论放前面在 Umi 4 中MPA 是内置能力通过配置开启目录摆对之后几乎不用额外代码。第一步把目录摆对下面这棵目录树验证的是 UmiJS MPA 的核心约定pages/下每个子文件夹就是一个页面文件夹里的index.tsx是入口见 examples/mpa/。my-mpa/ ├── .umirc.ts └── src/ ├── layouts/ │ └── basic.tsx └── pages/ ├── home/ │ └── index.tsx └── about/ └── index.tsx文件夹名就是页面名构建后会分别产出home.html和about.html。入口文件里只需导出一个 React 组件ReactDOM.render这些样板代码框架会帮你生成不用自己写。第二步用配置开启 MPA下面的.umirc.ts验证的是怎么让 Umi 进入 MPA 模式——只要出现mpa这个 key内置功能即启用源码里enableBy: api.EnableBy.config见 mpa.ts// .umirc.ts export default { mpa: {}, };第三步跑构建验证产物执行umi dev或umi build启动时控制台会打印一行[MPA] MPA Mode Enabled同样来自 mpa.ts这就是最直接的开关确认信号。构建完成后dist/里应该能看到home.html、about.html每个都是独立的完整 HTML——注意里面没有SPA 模式的umi.js和路由逻辑。三步走完dev server 已经能同时打开两个页面了。接下来花两分钟弄明白多是怎么来的后面调配置才不会玄学。它怎么多起来一个页面 一份独立 HTMLUmi 4 的 MPA 是真 MPA和 Umi 3 的模拟路由方案完全不同官方文档明确提示了两代实现的差异。它的内部流程其实就四步读一遍源码就能对上收集入口扫描src/pages/下的每个子目录找到index.tsx/ts/jsx/js每个目录生成一个 entry生成临时入口为每个页面写一份临时文件内容是import App from 你的页面加一段ReactDOM.createRoot(...).render(...)如果配了 layout 还会把Layout包在外面注册 webpack 入口modifyEntry钩子把 SPA 的umi入口删掉换成 N 个页面入口所以 MPA 产物里没有全局路由 bundle逐页面产 HTML给每个入口挂一个html-webpack-plugin输出页面名.html并把页面配置作为变量注入模板。这套机制解释了两件事。第一MPA 产物没有路由、没有 history页面之间跳转是整页刷新——访问哪个页面服务器就必须能直接吐出对应的.html这也是后面 404 问题的根源。第二文档里也说了MPA 模式下大量面向 SPA 的插件能力不可用它更适合作为构建工具来用所以别指望在 MPA 项目里继续用路由相关的插件。理解了机制下面这些配置项就不再是黑盒了——它们恰好分别作用在收集入口、注入模板、包裹布局这几个环节上。值得动手调的 4 个开关真正改变产物的 UmiJS MPA 配置页面级 config.json让每个页面有自己的标题和布局全局配置管所有页面config.json管单个页面。下面的例子验证的是页面级配置的完整写法title缺省时默认是目录名layout必须以/或绝对路径开头源码里有断言校验template可以让单个页面换模板// src/pages/about/config.json { title: 关于我们, layout: /layouts/basic, template: templates/marketing.html }如果不想每个页面都放一个config.json还有个替代方案在.umirc.ts里设mpa.getConfigFromEntryFile: true然后直接在入口文件里export const config { title: ... }导出配置。examples/mpa/ 用的就是这种方式两种写法选一种即可混用反而容易困惑。HTML 模板从默认模板到多模板切换不配任何模板时框架会用它内置的一份最小模板只有title和挂载点配了mpa.template就从项目根目录按路径找文件——注意路径解析起点是根目录不是src/。模板支持 lodash template 语法可用变量包括title、mountElementId等examples/mpa/templates/default.html 就是现成参照。多模板切换的思路很简单全局定一个默认模板再在特定页面的config.json里用template覆盖。下面这份营销页模板验证的是页面级模板如何拿到页面变量!-- templates/marketing.html -- !DOCTYPE html html head title% title % - 营销活动/title /head body div id% mountElementId %/div /body /html这里有个隐形约束模板里必须保留div id% mountElementId %React 就挂载在这个节点上删了它页面会白屏。layouts 复用一份布局套多个页面布局是套在页面组件外面的壳。全局写mpa.layout: /layouts/basic所有页面都会包上layouts/basic.tsx导出的组件某几个页面想换壳就在各自的config.json或export const config里写layout覆盖全局值。源码里这一步发生在临时入口生成阶段有 layout 就渲染LayoutApp //Layout没有就只渲染App /mpa.ts 的onGenerateFiles钩子。对营销站、文档站这种多数页面共用头部页脚、少数页面例外的结构这套全局 页面级覆盖的粒度正好够用。APP_ROOT 设置把应用根目录挪个位置默认情况下 Umi 以当前工作目录为根src/、.umirc.ts都从这里找。如果你的代码放在子目录里——典型场景是 Electron 混合应用仓库根目录放主进程渲染进程代码单独放在src/webview/——就可以用环境变量APP_ROOT指过去。下面的package.json片段验证了这种用法官方示例 examples/mpa-with-app-root-and-alias/ 里整个pages/、templates/都在src/webview/下{ scripts: { dev: APP_ROOTsrc/webview umi dev } }这个变量的读取逻辑很短就四行取process.env.APP_ROOT是相对路径就拼到当前工作目录下否则直接用没设置就退回当前目录。想确认它生效可以看 packages/umi/src/service/cwd.ts。顺带说清一个常见误解网上老文章里写的umi build --mpa命令行参数在 Umi 4 源码里并不存在——MPA 靠的是上文说的mpa配置项。真正影响构建行为的参数是环境变量MPA_FILTER页面多的项目 dev 启动慢时设MPA_FILTERhome,about就只收集这两个页面启动速度立竿见影mpa.ts 里的filterEntry函数。配置项就调到这儿。接下来把这些坑集中摆出来——出问题时直接对表不用从头翻机制。出问题了对照这张表现象根因处理访问页面 404 或内容错乱MPA 没有路由访问about不等于自动找到about.html服务器没做映射时会落到错误页面让 Web 服务器把路径映射到对应的.html或直接用/about.html访问同时确认页面目录符合pages/页面名/index.tsx约定产物还是 SPA有 umi.jsMPA 没生效.umirc.ts里没写mpa配置或写错了配置文件启动时确认控制台是否打印[MPA] MPA Mode Enabled没打印就是配置没被读到模板不生效改了 HTML 页面没变化mpa.template路径解析起点是项目根目录而非src/路径写不到文件或页面级config.json的template覆盖了全局值先核对路径能否从根目录解析到再查该页面的config.json是否有页面级template页面白屏自定义模板里漏了% mountElementId %挂载节点React 无节点可挂模板 body 中补回div id% mountElementId %/div配置了 layout 却报错/不生效源码断言要求layout必须是字符串且以/或/开头改成layout: /layouts/basic这类写法页面多了 dev 启动特别慢所有页面都作为入口参与构建用.env或命令行设置MPA_FILTERhome,about按需启动改了APP_ROOT但配置、页面全找不到APP_ROOT是相对当前工作目录解析的执行命令的目录不对确认在package.json所在目录执行脚本或改用绝对路径表里 90% 的坑本质都是路径解析起点和约定目录这两件事。对完表、修完问题剩下的就是上线前的例行检查了。从 Demo 到生产上线前检查清单 发布前逐项过一遍比出问题再排查快得多每个页面的title都显式设置了——不设置时会回退成目录名about页标题显示 about 这种事上线后很难看线上 Web 服务器配好了路径 →.html文件的映射SPA 习惯的 history fallback 在 MPA 下帮不了你模板里保留mountElementId挂载点head里的统计、SEO meta 信息按页面核对过不需要路由相关插件——MPA 模式下这些能力本就不可用依赖它们的代码要么删掉要么改写页面数量超过 10 个时本地和 CI 都用MPA_FILTER验证过按需构建的行为如果用了APP_ROOT确认 CI 脚本里环境变量同样传了——本地 dev 正常、线上构建找不到src/几乎都是漏了它构建产物里逐页抽查每个页面一份独立 HTML无umi.jstitle与config.json一致延伸阅读MPA 官方文档docs/docs/docs/guides/mpa.md最小可运行示例examples/mpa/APP_ROOT 实战示例examples/mpa-with-app-root-and-alias/MPA 功能实现源码packages/preset-umi/src/features/mpa/mpa.tsAPP_ROOT 读取逻辑packages/umi/src/service/cwd.ts完整文档站与全部示例入口docs/、examples/【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考