Umi MPA 模式完整指南无路由多页面构建实践【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umiUmi 内置的 MPA多页面应用模式将src/pages目录下的*/index.[jt]sx?文件直接作为 webpack 入口进行打包不生成路由、历史记录与umi.js适用于 H5 开发、小程序/插件开发等场景。本文基于 mpa.en-US.md 与仓库源码mpa.ts、extractExports.ts完整讲解 MPA 模式的配置项、约定式入口、页面级配置、模板定制与按需启动并给出可直接运行的示例。MPA 模式是什么Umi 支持传统的 MPA 模式在此模式下src/pages目录中的*/index.[jt]sx?文件会被当作 webpack 的 entry 进行打包。与默认的 SPA 模式不同MPA 模式不使用路由没有路由表、history也没有运行时框架代码umi.js页面即入口每个页面目录就是一个独立的打包入口构建产物为多个 HTML 文件更贴合传统多页场景满足 H5 开发、浏览器插件kitchen 插件开发等一页一入口的需求。从源码看MPA 功能由 packages/preset-umi/src/features/mpa/mpa.ts 实现通过api.EnableBy.config在用户配置了mpa后启用启动时会在终端打印黄色警告[MPA] MPA Mode Enabled。与 Umi 3 MPA 的区别需要注意Umi 4 的 MPA 与 Umi 3 的 MPA 是两种不同的实现Umi 3 的 MPA模拟路由渲染机制本质上仍是路由驱动Umi 4 的 MPA是真正的 MPA每个页面独立编译、独立输出 HTML不依赖路由系统。两者各有优劣。Umi 4 的 MPA 因为跳过了路由、SSR 等大量插件能力例如在 configPlugins.ts 中启用 MPA 后react-router、react-router-dom不再被注入 alias所以只适合作为纯构建工具使用不适合承载依赖路由能力的复杂应用。快速启用 MPAmpa是 Umi 内置功能无需额外安装插件通过配置即可开启// .umirc.ts export default { mpa: { template: string, getConfigFromEntryFile: boolean, layout: string, entry: object, }, }配置项说明配置项类型说明templatestring全局 HTML 模板路径例如template/index.html从项目根目录开始查找使用对应路径的index.html作为产物 HTML 模板getConfigFromEntryFileboolean是否从每个页面的入口文件src/*/index.tsx中读取独立配置开启后可免去config.jsonlayoutstring全局默认布局组件路径entryobject针对每个入口文件的配置例如{ foo: { title: ... } }可配置src/foo/index.tsx页面的title属性这些配置项在源码中的 schema 校验位于 mpa.ts使用 zod 定义为templatestring、layoutstring、getConfigFromEntryFileboolean、entryobject整体deepPartial即所有字段均可选。约定式入口文件MPA 的默认入口文件是src/pages目录下的*/index.[jt]sx?文件。目录结构示例 src/pages - foo/index.tsx - bar/index.tsx - hoo.tsx上面的结构中hoo.tsx因为不是目录/index.tsx形式不会被当作入口。扫描后生成的entry结构为{ foo: src/pages/foo/index.tsx, bar: src/pages/bar/index.tsx }构建后每个入口会生成对应的 HTML 文件产物为foo.html和bar.html。源码中入口收集逻辑位于 mpa.ts遍历src/pages目录下的每个子目录通过getIndexFile按index.tsx→index.ts→index.jsx→index.js的优先级查找入口文件随后在modifyEntry钩子中删除默认的umi入口并为每个页面注入mpa/${dir}/index.tsx临时入口最后在chainWebpack中为每个入口注册一个独立的html-webpack-plugin生成{entry.name}.html。页面级配置config.json约定方式在与入口文件同层目录放置config.json声明页面配置 src/pages foo - index.tsx - config.jsonfoo/config.json可为页面配置独立的layout和title{ layout: /layouts/bar.ts, title: foooooo }目前默认支持的页面级配置项包括template页面模板路径写法参考 html-webpack-plugin使用 lodash template 语法引用变量layout页面布局建议引用 src 目录下的文件并以/开头title页面标题默认为入口文件所在目录名mountElementId页面渲染时挂载节点的 id默认为root。源码中的getConfigmpa.ts会读取入口同层的config.json并调用checkConfig校验校验规则mpa.ts包括layout必须是 string且以/或/开头template、title必须是 stringhead、scripts必须是数组。getConfigFromEntryFileUmi 还实验性地支持另一种配置读取方式开启mpa: { getConfigFromEntryFile: true }后可以不用config.json直接在入口文件中通过export const config导出页面配置// src/pages/foo/index.tsx export const config { layout: /layouts/bar.ts, title: foooooo, }其底层实现是 extractExports.ts通过 esbuild 将入口文件打包为 CJS 格式注入ret x.config || {}的虚拟入口代码再以eval提取config导出对象。这也解释了为什么该功能被称为实验性——它依赖 esbuild 对入口文件的独立打包遇到复杂的依赖解析场景可能受限。注意getConfigFromEntryFile与config.json两种方式是互斥的collectEntry中会根据开关二选一读取配置。entry也可以在.umirc.ts中直接配置每个页面export default { mpa: { entry: { foo: { title: foo title } } } }源码中全局配置、页面配置文件与config.json的合并顺序为{ ...globalConfig, ...config }即.umirc.ts的entry配置会被config.json/export const config覆盖而title的最终取值优先级为globalConfig?.title || config.title || dirmpa.ts即显式配置优先缺省时回退到目录名。按需启动支持通过环境变量MPA_FILTER指定要启动的页面以提升构建速度# file .env # 只会启动 bar、foo 这两个页面 MPA_FILTERbar,foo对应源码为filterEntrympa.ts读取process.env.MPA_FILTER以逗号分隔后与目录名匹配未命中的目录直接跳过不参与入口收集与编译。渲染MPA 默认渲染方式为 React入口文件只需导出 React 组件即可被渲染无需自己编写ReactDOM.render逻辑export default function Page() { return divHello/div }生成的临时渲染文件mpa/${dir}/index.tsx内容由 mpa.ts 动态拼接引入App、按需引入Layout并根据 React 版本选择渲染 API——React 18 及以上使用ReactDOM.createRoot(...).render(...)并从react-dom/client引入React 17 及以下使用ReactDOM.render(...)并从react-dom引入。默认启用 React 18。如果需要 React 17 的渲染方式请在项目中安装 React 17 依赖框架会自动适配 React 版本$ pnpm i react17 react-dom17自定义 HTML 模板MPA 默认模板如下!DOCTYPE html html head title% title %/title /head body div id% mountElementId %/div /body /html通过template配置可以自定义全局 HTML 模板也可以在页面级配置中为不同页面指定不同模板。请确保模板中至少包含% title %和% mountElementId %两个变量。模板选择逻辑mpa.ts优先级为页面级entry.template→ 全局api.config.mpa.template→ 内置默认模板mpa/template.html。模板路径会以api.cwd项目根目录为基准resolve。模板中的变量通过templateParameters: entry注入因此页面配置中的title、mountElementId以及自定义字段如description都可以在模板中通过% %引用。仓库自带的示例 examples/mpa 展示了完整用法templates/default.html中额外引用了% description %变量pages/foo/config.json配置了titlepages/foo/index.tsx同时导出了config用于演示getConfigFromEntryFile并使用useState验证 MPA 下 hooks 与 mfsu 的兼容性。示例的启动与构建命令为npm run dev与npm run build见 examples/mpa/package.json。总结Umi 4 的 MPA 模式是一个真实的多页面构建方案每个页面独立入口、独立 HTML 产物无路由、无 history、无umi.js天然适合 H5、插件等传统多页场景。使用时需注意它跳过了大量依赖路由的插件能力仅适合作为纯构建工具同时它提供了config.json、export const config、全局entry三种页面配置方式以及MPA_FILTER按需启动能力配合可定制的 HTML 模板足以覆盖从简单多页到复杂定制的大部分需求。【免费下载链接】umiA framework in react community ✨项目地址: https://gitcode.com/GitHub_Trending/um/umi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
