UmiJS MPA架构实战指南：从配置到优化的避坑全解

🔍 问题引入：MPA模式下的典型困境

在现代前端开发中，多页面应用（MPA模式 - 多页面应用架构）依然是企业官网、营销活动页等场景的首选方案。然而在UmiJS框架中配置MPA时，开发者常面临三大痛点：路由规则冲突导致页面404、自定义模板不生效、构建产物与预期不符。某电商项目曾因MPA配置不当导致首屏加载时间增加300%，最终通过规范目录结构和优化构建参数将性能恢复正常。

🧩 核心原理：UmiJS MPA的工作机制

UmiJS的MPA实现基于"约定大于配置"的设计理念，通过目录结构自动生成独立HTML文件。与SPA（单页应用）共享一个HTML入口不同，MPA模式会为每个页面创建独立的构建入口，其核心处理流程包括：

1. 目录扫描：遍历pages目录识别页面入口
2. 路由生成：根据目录结构自动映射路由规则
3. 模板渲染：将页面组件注入指定HTML模板
4. 资源打包：为每个页面生成独立的JS/CSS资源

注意：Umi v4对MPA的支持更加完善，建议使用v4.0.0+版本以获得最佳体验

🛠️ 实践指南：从零配置MPA项目

基础目录结构

examples/mpa/
├── layouts/           # 布局组件目录
├── pages/             # 页面目录（核心）
│   ├── about/         # 关于我们页面
│   │   └── index.tsx  # 页面入口文件
│   └── home/          # 首页
│       ├── index.tsx  # 页面组件
│       └── config.json # 页面配置
└── templates/         # HTML模板目录
    └── default.html   # 默认模板

关键配置项详解

1. config.json页面配置

// pages/home/config.json
{
  "title": "首页 - Umi MPA示例",  // 页面标题
  "template": "home.html",       // 指定模板文件
  "mountElementId": "root"       // 应用挂载节点ID
}

适用场景：需要为特定页面设置独立标题、元数据或自定义挂载点时使用

2. 动态路由配置

// .umirc.ts
export default defineConfig({
  routes: [
    { 
      path: '/user/:id', 
      component: './pages/user/index',
      // 动态路由MPA配置
      mpa: {
        // 生成静态HTML的参数列表
        staticParams: [{ id: '1001' }, { id: '1002' }]
      }
    }
  ]
})

适用场景：需要预渲染有限数量的动态路由页面（如产品详情页）

3. 环境变量管理

// package.json
{
  "scripts": {
    "dev": "APP_ROOT=src/pages umi dev",  // 指定应用根目录
    "build:prod": "UMI_ENV=production umi build --mpa"
  }
}

适用场景：大型项目需要分离源码目录或多环境构建时

配置检查清单

检查项	配置要求	常见错误
目录结构	pages/[page]/index.tsx	错误使用pages/[page].tsx直接作为入口
模板文件	放置于templates目录	模板文件未使用UTF-8编码
路由配置	动态路由需设置staticParams	未设置导致构建失败
构建命令	必须添加--mpa参数	遗漏参数导致构建为SPA模式

📊 案例分析：企业官网MPA实现

项目背景

某科技公司官网需要实现8个独立页面，包含首页、产品介绍、解决方案等模块，要求各页面可独立部署且共享公共组件库。

关键技术点

1. 共享布局实现

// layouts/MainLayout.tsx
import { Outlet } from 'umi';

export default function MainLayout() {
  return (
    <div className="main-layout">
      <header>企业官网导航</header>
      <main><Outlet /></main>
      <footer>版权信息</footer>
    </div>
  );
}

// 在页面中使用
// pages/home/index.tsx
import MainLayout from '../../layouts/MainLayout';

export default function HomePage() {
  return <div>首页内容</div>;
}

HomePage.Layout = MainLayout;  // 指定页面布局

2. 多环境构建配置

// config/config.ts
export default defineConfig({
  define: {
    'process.env.PAGE_TYPE': process.env.UMI_ENV === 'production' ? 'official' : 'demo',
  },
  // 不同环境使用不同模板
  mpa: {
    template: process.env.UMI_ENV === 'production' ? 'prod.html' : 'dev.html'
  }
});

3. 性能优化措施

• 配置splitChunks提取公共代码
• 使用dynamicImport实现路由懒加载
• 开启mfsu加速构建

🚦 常见错误诊断流程图

开始诊断 → 检查目录结构 → pages/[page]/index.tsx是否存在
  ↓
是 → 检查模板文件 → templates/default.html是否存在
  ↓
是 → 检查构建命令 → 是否包含--mpa参数
  ↓
是 → 检查路由配置 → 是否存在冲突路由
  ↓
否 → 问题解决

💡 经验总结

1. 开发环境差异

   • Windows：环境变量设置需使用set APP_ROOT=src && umi dev格式
   • macOS/Linux：使用APP_ROOT=src umi dev格式
   • 建议使用cross-env包统一跨平台环境变量设置

2. 最佳实践

   • 页面数量超过10个时，建议按业务模块拆分pages目录
   • 公共组件提取到components目录统一管理
   • 使用config.json维护页面元数据，便于SEO优化

3. 性能优化

   • 合理设置mpa.exclude排除无需独立构建的页面
   • 利用scriptsPreload配置预加载关键资源
   • 生产环境开启cssnano压缩CSS

通过本文介绍的配置方法和避坑指南，你可以轻松构建高性能的UmiJS MPA应用。更多高级特性可参考官方文档，遇到问题可在社区寻求帮助。

官方文档：docs/
社区讨论：CONTRIBUTING.md