Umi框架问题攻坚：Mako构建工具与Unocss原子化CSS的执行顺序优化实践

在现代前端开发中，Umi框架以其插件化架构和丰富生态深受开发者青睐。然而，当集成Mako构建工具与Unocss原子化CSS框架时，许多开发者遭遇了"开发环境正常，生产环境样式丢失"的诡异现象。本文将从问题诊断入手，深入剖析编译流程冲突的底层原因，提供经过验证的分步解决方案，并构建完整的验证体系与最佳实践指南。

现象诊断：环境差异导致的样式异常

典型症状表现

集成Mako与Unocss的Umi项目通常会出现以下特征性问题：

• 开发环境（umi dev）：所有Unocss原子化样式（如flex justify-center）均正常生效，元素布局符合预期
• 生产环境（umi build）：构建产物中缺失部分或全部原子化样式，导致页面布局错乱
• 排查难点：无报错信息，构建过程显示成功，仅在浏览器中表现为样式异常

初步诊断方法

通过以下步骤可快速定位问题根源：

1. 执行生产构建并检查输出日志：

umi build > build.log 2>&1

2. 分析构建产物中的CSS文件（通常位于dist/umi.css），搜索Unocss特征类名：

grep "flex items-center" dist/umi.css

3. 对比开发与生产环境的DOM结构，观察原子化类名是否被正确转换

若生产环境CSS中完全缺失Unocss生成的类规则，基本可确定为编译顺序冲突问题。

技术原理：Umi插件执行机制与冲突根源

Umi插件系统架构

Umi框架的插件系统采用阶段式执行模型，核心逻辑在packages/core/src/service/plugin.ts中实现。插件通过声明stage属性决定执行顺序，数值越小越早执行。默认情况下：

• Mako构建插件（@umijs/features/mako/mako）注册于stage 0（早期阶段）
• Unocss插件（@umijs/plugin-unocss）注册于stage 100（默认阶段）

这种执行顺序导致Unocss生成的原子化样式无法被Mako的资源打包流程捕获。

冲突时序图

以下是默认配置下的构建流程时序：

sequenceDiagram
    participant Umi Core
    participant Mako Bundler
    participant Unocss Plugin
    participant CSS Processing
    
    Umi Core->>Mako Bundler: 启动资源打包(stage 0)
    Mako Bundler->>CSS Processing: 处理原始CSS文件
    Note over Mako Bundler,CSS Processing: 此时Unocss尚未执行
    CSS Processing->>Mako Bundler: 返回未处理的CSS
    Mako Bundler->>Umi Core: 完成资源打包
    Umi Core->>Unocss Plugin: 执行样式转换(stage 100)
    Unocss Plugin->>Umi Core: 生成原子化样式
    Note over Unocss Plugin,Umi Core: 样式生成于打包完成后，无法被捕获

从packages/preset-umi/src/index.ts的插件注册列表可见，Mako相关插件确实优先于样式处理插件加载，这是导致生产环境样式丢失的根本原因。

解决方案：插件执行顺序优化

核心解决思路

解决此问题需通过Umi插件API调整Unocss的执行阶段，确保其样式生成过程发生在Mako资源打包之前。以下是完整的实施步骤：

步骤1：创建插件优先级调整文件

在项目根目录创建plugin-unocss-priority.ts，通过修改配置提升Unocss执行优先级：

// plugin-unocss-priority.ts
import { IApi } from '@umijs/types';

export default (api: IApi) => {
  // 在配置修改阶段调整插件顺序
  api.modifyConfig((memo) => {
    if (!memo.plugins) return memo;
    
    memo.plugins = memo.plugins.map(plugin => {
      // 识别Unocss插件并调整其执行阶段
      if (typeof plugin === 'string' && plugin.includes('unocss')) {
        return {
          path: plugin,
          // 设置为极高优先级，确保在Mako之前执行
          stage: -Infinity
        };
      }
      // 处理对象形式的插件配置
      if (typeof plugin === 'object' && plugin.path && plugin.path.includes('unocss')) {
        return {
          ...plugin,
          stage: -Infinity
        };
      }
      return plugin;
    });
    return memo;
  });
};

步骤2：配置文件调整

修改项目根目录的.umirc.ts（或config/config.ts），注册自定义插件并配置Unocss：

// .umirc.ts
import { defineConfig } from 'umi';
import unocssConfig from './unocss.config';

export default defineConfig({
  // 确保自定义插件优先注册
  plugins: [
    './plugin-unocss-priority.ts',
    '@umijs/plugin-unocss',
  ],
  // Unocss配置
  unocss: {
    ...unocssConfig,
    // 强制在生产环境生成完整样式
    envMode: 'build',
    // 启用调试模式便于问题排查
    debug: process.env.NODE_ENV === 'development',
  },
  // 明确指定使用Mako构建工具
  bundler: 'mako',
  // 其他项目配置...
});

步骤3：验证插件加载顺序

执行Umi的插件检查命令，确认Unocss已优先于Mako加载：

umi inspect plugins | grep -E 'mako|unocss'

预期输出（注意stage数值）：

- ./plugin-unocss-priority.ts (stage -Infinity)
- @umijs/plugin-unocss (stage -Infinity)
- @umijs/features/mako/mako (stage 0)

替代方案对比

解决方案	实施难度	适用场景	潜在风险
插件stage调整	低	大多数Umi项目	可能与其他插件顺序冲突
自定义Webpack配置	中	需深度定制构建流程	破坏Umi插件生态
使用Vite替代Mako	高	新项目或无Mako依赖	可能引入新的兼容性问题
预生成Unocss样式	中	静态站点	开发体验下降，样式冗余

验证体系：全场景测试策略

开发环境验证

1. 启动开发服务器：

umi dev

2. 访问页面并打开浏览器开发者工具，检查元素类名是否被Unocss正确处理：

   • 原始类名：class="flex items-center justify-between p-4"
   • 转换后：class="flex items-center justify-between p-4 umi-unocss-xxxx umi-unocss-yyyy umi-unocss-zzzz"

3. 验证热更新功能：修改组件类名，确认样式实时更新。

生产环境验证

1. 执行生产构建：

umi build

2. 启动本地预览服务器：

umi preview

3. 关键验证点：
   • 检查dist/umi.css是否包含Unocss生成的样式规则
   • 使用浏览器网络面板确认CSS文件加载正常
   • 测试响应式布局在不同设备尺寸下的表现

自动化测试集成

为确保长期稳定性，建议添加构建后验证脚本：

# 在package.json中添加
{
  "scripts": {
    "build:verify": "umi build && grep -q 'umi-unocss' dist/umi.css && echo 'Unocss build verification passed'"
  }
}

执行验证命令：

npm run build:verify

最佳实践：版本兼容与风险规避

版本兼容矩阵

Umi版本	Mako版本	Unocss插件版本	推荐配置
4.0.x - 4.1.x	1.0.x - 1.1.x	1.0.x	stage: -Infinity
4.2.x+	1.2.x+	1.1.x+	stage: 50
4.3.x+	2.0.x+	2.0.x+	无需额外配置

风险规避策略

1. 版本锁定：在package.json中明确指定版本：

{
  "dependencies": {
    "@umijs/bundler-mako": "1.2.3",
    "@umijs/plugin-unocss": "1.1.0"
  }
}

2. 构建缓存清理：遇到样式异常时，执行：

umi build --clean

3. 插件冲突检测：定期执行插件检查：

umi inspect plugins > plugin-order.log

扩展应用场景

本解决方案的核心思想——插件执行顺序优化——可应用于其他类似的Umi集成场景：

1. 多CSS预处理器集成：如同时使用Less和Stylus时的处理顺序调整
2. 自定义资源处理器：确保自定义资源加载器在打包流程前执行
3. 国际化与主题系统：控制i18n与主题样式的生成顺序
4. 性能优化插件：确保代码分割和懒加载插件的正确执行时机

通过掌握Umi插件的stage配置机制，开发者可以更灵活地控制构建流程，解决各类工具集成冲突，构建更高效、更稳定的前端应用。

在实际项目中，建议结合packages/core/src/service/plugin.ts中的插件管理源码，深入理解Umi的插件执行模型，为复杂场景下的构建流程优化打下基础。