UmiJS MPA 配置 5 个关键点构建后子页面 404 怎么破【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi上周帮一个同事排障项目上了静态服务器首页正常点开子页面直接 404。检查一圈发现框架还在按单页应用出包dist 里只有一个 index.html其余页面全靠前端路由拼路径静态服务自然接不住。把 UmiJS MPA 模式开启后框架按 pages 目录为每个页面单独出一个 HTML部署形态完全不同。这篇按从 0 到 1 搭出可用 MPA 项目的顺序把 UmiJS MPA 配置会碰到的坑一次讲完对照官方示例 examples/mpa/ 操作即可。先分清两种模式产出的差别同一个入口文件两种模式出包结果如下单页应用MPA 模式HTML 产物仅一个 index.html每个入口各出一份 html路由 / history有无页面即文件umi.js 运行时有无说白了MPA 模式更接近用 umi 当打包器框架不会注入路由层页面地址天然就是/foo.html这种形态静态部署也不需要任何 history 回退规则。官方示例的构建脚本就是普通命令 examples/mpa/package.json{ scripts: { build: umi build, // 无需额外 CLI 参数MPA 由配置项驱动 dev: umi dev } }开启 mpa 配置项最小可跑在config.ts里加一个空对象就能启动import { defineConfig } from umi; export default defineConfig({ mpa: {}, // 空对象即可启用其余字段按需填 });执行umi build逐个打开 dist 下的foo.html、bar.html标题和挂载节点各就各位骨架就算通了。目录约定一个文件夹对应一个页面入口⚠️ 子页面 404 的头号原因就是页面压根没进 entry 列表。规则很机械扫描pages下的子文件夹目录名即页面名文件夹内必须存在入口文件index.tsx.ts/.jsx/.js也认。散落在 pages 根目录下的独立文件一律忽略。pages/ ├── foo/ │ ├── index.tsx # foo 页入口缺了它整页不存在 │ └── config.json # 页面级配置可选 └── bar/ └── index.tsx目录结构参考 examples/mpa/。入口里只负责导出 React 组件挂载逻辑由框架生成不用手写// pages/foo/index.tsx export default () divHello Foo/div; // 无需 ReactDOM.renderReact 17 / 18 的渲染 API 差异框架会自动适配装了哪个版本就用哪种写法。页面级 config.jsontitle、layout 各归各页入口同目录放一个config.json只影响当前页面。实际支持四个字段title、layout、template、mountElementId挂载节点 id默认root。{ title: title from config.json, // 缺省则回退为目录名 layout: /layouts/basic // 路径必须以 / 或 / 开头 }实例见 examples/mpa/pages/foo/config.json。不想多一个文件的话也可以在入口里直接导出配置// config.ts mpa: { getConfigFromEntryFile: true, // 改为从入口文件的 export const config 读取 },// pages/foo/index.tsx export const config { title: foooooo, layout: /layouts/foo };两种写法二选一官方示例 examples/mpa/pages/foo/index.tsx 用的就是导出方式。自定义 HTML 模板命名与两个必留变量⚠️ 模板改了不生效九成是路径写错了层级或者变量被删了。模板写法兼容 lodash template两个变量是硬性要求!-- templates/default.htmltitle 与 mountElementId 缺一不可 -- title% title %/title div id% mountElementId %/div官方示例模板见 examples/mpa/templates/default.html。开启方式分两级mpa: { template: templates/default.html, // 全局模板路径从项目根目录解析 },单个页面要换模板就在该页的config.json里写template字段覆盖全局值。布局复用入口文件里一行都不用写全局默认布局配在mpa.layout单页布局写在config.json同样要求/或绝对路径。框架会为每个页面生成临时入口把页面组件包进LayoutApp //Layout再渲染所以页面文件本身不需要 import 布局mpa: { layout: /layouts/basic, // 所有页面共用的兜底布局 },布局实现就是个普通组件透传children即可参考 examples/mpa/layouts/basic.tsx。页面级配置优先于全局bar页不写 layout 就用全局这份。APP_ROOT 把源码挪出默认位置⚠️ 源码不在项目根Electron 渲染进程、monorepo 子包最常见框架找不到 pages、layouts 目录现象是入口收集为空、一个页面都打不出来。解法是在启动命令上带APP_ROOT环境变量把约定目录的基准挪过去示例工程见 examples/mpa-with-app-root-and-alias/{ scripts: { dev: APP_ROOTsrc/webview umi dev // pages 实际位于 src/webview/pages } }页面多到构建太慢时还可以用MPA_FILTERbar,foo只启动指定页面。部署前自查清单config.ts已开启mpa每个页面是pages/目录名/index.tsx结构无裸文件页面级配置放在入口同目录的config.json自定义模板保留了% title %与% mountElementId %layout路径以/或/开头源码根目录变更时已同步设置APP_ROOTFAQQ1子页面 404 怎么排查先看构建日志有没有[MPA] Collect Entries输出确认页面进了 entry 列表再看 dist 里是否存在对应 html。九成是没开mpa或者入口结构不符合文件夹 index.tsx约定。Q2模板文件改了页面没变化确认改的是mpa.template指向的全局模板还是页面config.json里的template字段注意全局路径从项目根目录解析别写成相对入口的路径。Q3MPA 模式能用多少 umi 插件定位上它更接近纯构建工具路由、history 相关能力都不存在插件可用性明显少于单页模式选型前想清楚。UmiJS MPA 配置的全部动作就停在这几处开配置、守目录约定、管好页面级配置与模板、布局交给约定、根目录变更用环境变量声明。照这份顺序走一遍从搭建到上线基本不会再踩 404 这类低级故障。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考