排查 UmiJS 常见构建报错与路由失效问题

一、UmiJS 故障排查标准操作流程

当遇到项目无法编译通过或页面跳转后显示空白时，盲目尝试修改业务代码往往会引入更多不可控因素。UmiJS 具有强内聚与高度封装的架构特性，所有路由、插件及运行时逻辑都会在 src/.umi（或临时生成目录）中完成代码装配。因此，按照由易到难、由缓存到配置的标准步骤进行分级排查，是最高效的排错方式。

按照上述流程推进时，请特别注意第一步的缓存清理。Umi 4 引入了 umi setup 命令，用于根据当前项目配置和约定目录重新生成 .umi 下的运行时类型、导出文件和路由清单。很多看似离奇的类型引用缺失和模块未定义报错，在执行 npx umi setup 后便会自动解除。

二、典型构建报错诊断与修复方案

UmiJS 的构建底层依托 Webpack 5 或 Vite，并叠加了自研的 MFSU（Module Federation Speed Up）模块提速方案。了解构建管道各节点的运作方式，有助于快速根据终端输出定位故障根源。

1. MFSU 预编译错误与依赖冲突

现象表现：执行 npm run dev 或 umi build 时，终端输出类似 [MFSU] build failed，或者提示某个第三方依赖包内部导出未定义（如 export 'xxx' was not found in 'yyy'）。

原因解释：MFSU 的核心机制是通过模块联邦将 node_modules 中的三方依赖提前独立打成 Chunk，并在本地生成持久化缓存。如果项目安装了新的依赖包、修改了 package.json 中的版本，或者使用了同时包含 CommonJS 和 ESM 混合导出的老旧库，MFSU 的依赖分析器可能会由于缓存未更新而出现模块映射死锁。

修复步骤：

• 第一步：手动清除 MFSU 本地缓存。Umi 4 默认缓存在 node_modules/.cache/mfsu 目录下。
• 第二步：如果某个特定包（例如复杂的图表库或带有原生 Node 依赖的包）频繁报错，可在配置文件中将其从 MFSU 预编译清单中排除，或者使用 unMatchLibs 配置。

import { defineConfig } from 'umi';

export default defineConfig({
  // 方式一：针对特定冲突包排除 MFSU 预编译（以 monaco-editor 或特定包为例）
  mfsu: {
    exclude: ['monaco-editor', 'some-legacy-package'],
    shared: {
      react: { singleton: true },
      'react-dom': { singleton: true },
    },
  },

  // 方式二：在排查故障阶段，如果需确认是否为 MFSU 引起，可临时设为 false 测试构建
  // mfsu: false,
});

2. TypeScript 别名路径与模块未找到（Module not found）

现象表现：构建时报错 Module not found: Can't resolve '@/components/Header' in ...，但在代码编辑器中路径可以正常跳转。

原因解释：VSCode 等编辑器依据的是项目根目录下的 tsconfig.json，而 UmiJS 编译构建是由 Webpack/Babel 的 alias 配置驱动的。如果开发者自行覆盖了 tsconfig.json 的 paths 属性，或者配置了非标准的子目录别名，却未在 .umirc.ts 中配置对应的 alias，就会导致“编辑器不报错但构建失败”。

修复步骤：确保 .umirc.ts 中的 alias 与 tsconfig.json 保持对称同步。

// 1. .umirc.ts 中显式声明 alias
import { defineConfig } from 'umi';
import path from 'path';

export default defineConfig({
  alias: {
    '@': path.resolve(__dirname, 'src'),
    '@components': path.resolve(__dirname, 'src/components'),
    '@utils': path.resolve(__dirname, 'src/utils'),
  },
});

// 2. tsconfig.json 同步配置
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}

3. 构建过程中内存溢出（JavaScript heap out of memory）

现象表现：在执行生产构建 umi build 的后半段（通常在 Terser/esbuild 代码压缩或 SourceMap 生成阶段），终端抛出 FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory。

原因解释：Node.js 在 64 位系统下默认的最大老生代内存上限约为 1.4GB ~ 2GB。当大型企业级项目包含大量页面、多语言包及巨大的 SourceMap 时，Webpack 5 内存开销会突破默认上限。

修复步骤：在 package.json 构建脚本中通过 --max-old-space-size 调高 Node 内存上限，并在 Umi 配置中关闭非必要的生产环境 SourceMap。

// package.json scripts 调整
{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=4096 umi build"
  }
}

// .umirc.ts 关闭生产环境巨大 sourceMap 消耗
export default defineConfig({
  devtool: process.env.NODE_ENV === 'development' ? 'eval-cheap-module-source-map' : false,
  hash: true,
});

三、路由失效与 404/白屏深度排查

UmiJS 的路由系统支持约定式路由（Conventional Routing）与配置式路由（Configured Routing）。很多开发者在混合使用或调整目录结构时，由于未理解 Umi 的路由解析优先律，经常出现“页面文件存在却访问 404”或“点击跳转后页面呈现白屏”的故障。

1. 配置式与约定式路由互斥问题

这是初学者最容易陷入的盲区。一旦在 .umirc.ts 或 config/config.ts 中配置了 routes 选项，UmiJS 将自动彻底关闭约定式路由扫描。

典型表现：开发者在 src/pages/order/index.tsx 下新建了文件，并在浏览器直接访问 http://localhost:8000/order，页面提示 404 或者重定向到了首页。

排查与修复：

• 检查项目中是否存在 routes 配置项。如果有，任何新增的页面必须在 routes 列表中显式登记。
• 若希望采用约定式路由，则必须将配置文件中的 routes 字段完全移除或注释掉。

// .umirc.ts
export default defineConfig({
  routes: [
    // 根布局
    {
      path: '/',
      component: '@/layouts/index',
      routes: [
        { path: '/', redirect: '/home' },
        { path: '/home', component: '@/pages/home' },
        // 动态路由传参必须保持参数占位符格式一致
        { path: '/order/:orderId', component: '@/pages/order/detail' },
        // 404 兜底路由必须放置在当前嵌套的最末端
        { path: '*', component: '@/pages/404' },
      ],
    },
  ],
});

2. 嵌套布局中子组件不渲染（白屏）

现象表现：页面 URL 正常变化，浏览器 Network 面板没有报错，但主内容区域完全空白。

原因解释：Umi 4 升级到了 React Router 6，嵌套路由的渲染机制从 props.children 全面变更为 <Outlet /> 组件。很多从 Umi 3 迁移到 Umi 4 的项目，仍在使用 {children}，导致子组件挂载点缺失。

修复代码：检查 src/layouts/index.tsx 或各层级父组件的出口渲染方式。

// src/layouts/index.tsx
import React from 'react';
import { Outlet, Link } from 'umi';

export default function BasicLayout() {
  return (
    <div className="layout-wrapper">
      <aside>
        <nav>
          <Link to="/home">首页</Link>
          <Link to="/order/1001">订单详情</Link>
        </nav>
      </aside>
      <main>
        {/* Umi 4 必须在此声明 Outlet 占位符 */}
        <Outlet />
      </main>
    </div>
  );
}

3. 生产环境构建后刷新直接报 404 错误

现象表现：通过 npm run dev 本地预览一切正常，但执行 umi build 部署到 Nginx 或静态托管平台后，首次进入首页正常，点击跳转正常，但在非首页路径（如 /order/detail）手动按 F5 刷新时，浏览器直接报 Nginx 404 Not Found。

原因解释：UmiJS 默认使用 HTML5 browser 路由模式（History 模式）。在这种模式下，页面跳转是通过 window.history.pushState 在前端控制的，服务器本身并不存在 /order/detail/index.html 实体文件。当用户刷新浏览器时，浏览器向服务端发起真实 HTTP GET 请求，Nginx 在静态根目录找不到对应目录文件，默认返回 404。

修复方案：配置 Nginx 的 try_files 规则，将所有未命中物理文件的请求全部回退指向 index.html，交给前端 UmiJS 运行时接管。

server {
    listen       80;
    server_name  app.example.com;

    # 1. 如果部署在网站根路径 (base: '/', publicPath: '/')
    location / {
        root   /var/www/my-umi-app/dist;
        index  index.html index.htm;
        # 核心关键行：找不到文件时回退到 index.html
        try_files $uri $uri/ /index.html;
    }

    # 2. 如果部署在二级子目录 (base: '/subpath/', publicPath: '/subpath/')
    location /subpath {
        alias  /var/www/my-umi-app/dist;
        index  index.html index.htm;
        # 子目录回退指向该子路径下的 index.html
        try_files $uri $uri/ /subpath/index.html;
    }
}

四、构建报错与路由失效速查矩阵

为了便于在日常开发与应急排障中迅速找到应对措施，下表系统总结了 UmiJS 最核心的几类报错特征、根本诱因与快速解决手段。

总结与日常防御建议

排查 UmiJS 构建报错与路由失效问题，关键在于建立清晰的边界感：

1. 看清阶段：终端报出的红色错误属于编译期（Webpack/Babel/MFSU），优先清理 .umi 和 node_modules/.cache 并核对依赖；浏览器控制台报错或视图空白属于运行时（React/路由解析），优先排查 Outlet 占位与路由匹配树。
2. 保持规范：如果选择配置式路由，就务必养成每次新增页面即在配置文件登记的习惯，不要指望约定式与配置式自动融合；如果涉及多层嵌套，务必在 Umi 4 中统一使用 <Outlet />。
3. 生产对齐：涉及二级路径发布或非根目录部署时，始终保持 base 与 publicPath 尾部斜杠一致，并在 Web 服务器（如 Nginx）上配妥 try_files 兜底，彻底消除静态页面刷新 404 隐患。