Umi项目中Mako与Unocss样式冲突难题：编译顺序优化解决策略

2026-03-14 04:17:03作者：鲍丁臣Ursa

在现代前端开发中，Umi作为React生态的重要框架，常与Mako构建工具和Unocss原子化CSS框架配合使用。然而，许多开发者在使用这一组合时会遇到一个棘手问题：开发环境下样式显示正常，但生产环境构建后出现样式丢失或布局错乱。这种"环境不一致"现象往往源于Mako与Unocss的编译顺序冲突，本文将通过系统化的解决方案，帮助开发者彻底解决这一技术难题。

问题场景：开发与生产环境的样式差异

某团队在基于Umi 4构建的管理系统中集成了Unocss，开发过程中使用umi dev命令时，所有原子化样式都能正常显示。但当执行umi build打包部署后，生产环境页面出现大量样式丢失，按钮、卡片等组件布局完全错乱。通过浏览器开发者工具检查发现，Unocss定义的原子化类名（如flex items-center justify-between）在生产环境中未被正确转换为实际CSS规则。

进一步排查发现，问题并非Unocss配置错误，而是Mako构建工具在处理资源时，未能包含Unocss生成的原子化样式。这种现象在大型项目中尤为常见，因为随着代码规模增长，构建流程的执行顺序对最终输出结果的影响会更加显著。

技术原理：构建流程中的执行顺序冲突

要理解这一问题的本质，我们需要先了解Umi框架的插件执行机制。Umi采用基于阶段(stage)的插件系统，每个插件可以指定在特定阶段执行，阶段数值越小，执行时间越早。默认情况下，Mako作为官方推荐的构建工具（bundler），其插件会在较早阶段（stage 0）执行，而Unocss插件则在较晚阶段执行。

这种执行顺序就好比餐厅厨房的工作流程：Mako是负责最终烹饪的厨师，而Unocss是提供特殊调料的供应商。如果厨师先完成烹饪，供应商才送来调料，那么最终菜品自然无法获得应有的风味。同样地，当Mako已经完成资源打包，Unocss才生成原子化样式，这些样式自然无法被包含在最终的CSS文件中。

sequenceDiagram
    participant Umi Core
    participant Mako Bundler
    participant Unocss Plugin
    participant CSS Output

    Umi Core->>Mako Bundler: 启动资源打包(stage 0)
    Mako Bundler->>CSS Output: 处理并输出CSS
    Note over Mako Bundler,CSS Output: 此时Unocss尚未运行
    Unocss Plugin->>CSS Output: 生成原子化样式(stage 100)
    Note over Unocss Plugin,CSS Output: 样式生成太晚，无法被Mako捕获
    CSS Output-->>Umi Core: 缺少原子化样式的结果

Umi的插件系统在Plugin类中实现了阶段管理逻辑，通过stage属性控制插件执行顺序。在preset-umi的默认配置中，Mako相关插件被设置为优先执行，这就是导致Unocss样式被忽略的根本原因。

解决方案：三步实现编译顺序优化

诊断：确认插件执行顺序

在开始修改配置前，我们需要先确认当前项目的插件加载顺序。执行以下命令可以列出所有插件及其执行阶段：

umi inspect plugins

在输出结果中查找与Mako和Unocss相关的插件，正常情况下会看到类似这样的顺序：

- @umijs/features/mako/mako (stage 0)
- @umijs/plugin-unocss (stage 100)

这种顺序表明Mako确实在Unocss之前执行，验证了我们的诊断。

注意事项：确保Umi版本在4.0.0以上，因为早期版本可能不支持插件阶段的自定义配置。可以通过umi -v命令检查当前版本。

实施：调整Unocss执行阶段

要解决执行顺序问题，我们需要创建一个自定义插件来调整Unocss的执行阶段。在项目根目录下创建plugin-unocss-priority.ts文件：

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

export default (api: IApi) => {
  // 通过修改配置调整Unocss插件的执行阶段
  api.modifyConfig((config) => {
    // 遍历所有插件配置
    config.plugins = config.plugins?.map(pluginItem => {
      // 识别Unocss插件
      if (typeof pluginItem === 'string' && pluginItem.includes('unocss')) {
        // 将字符串形式的插件配置转换为对象形式
        return {
          path: pluginItem,
          // 设置为最大安全整数，确保在所有插件之后执行
          stage: Number.MAX_SAFE_INTEGER
        };
      }
      return pluginItem;
    });
    return config;
  });
};

接下来，修改项目的Umi配置文件.umirc.ts，注册自定义插件并配置Unocss：

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

export default defineConfig({
  // 注册自定义优先级插件，确保在Unocss之前加载
  plugins: [
    './plugin-unocss-priority.ts',
    '@umijs/plugin-unocss',
  ],
  // Unocss配置
  unocss: {
    ...unocssConfig,
    // 强制在构建模式下生成样式
    envMode: 'build',
    // 开启调试模式，便于排查问题
    debug: process.env.NODE_ENV === 'development',
  },
  // 明确指定使用Mako作为构建工具
  bundler: 'mako',
});

验证：确认配置生效

完成配置修改后，再次执行插件检查命令：

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

现在应该看到Unocss插件的执行阶段已被调整：

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

这表明我们的自定义插件已成功将Unocss的执行阶段调整为最后，确保其生成的样式能被Mako正确捕获。

验证方法：全流程效果确认

为确保解决方案有效，我们需要在开发和生产环境分别进行验证：

开发环境验证

启动开发服务器：

umi dev

访问应用并打开浏览器开发者工具，检查任意使用Unocss类名的元素。在Elements面板中，应该能看到类似uno-abc123的哈希类名，且对应的CSS规则已正确应用。

生产环境验证

构建并预览生产版本：

umi build && umi preview

在预览页面中，同样检查元素的类名和CSS规则。特别注意查看生成的CSS文件（通常位于dist/umi.css），应该包含Unocss生成的原子化样式规则。

自动化验证

为避免手动验证的繁琐，可以在CI/CD流程中添加自动化检查：

# 构建项目
umi build

# 检查CSS文件中是否包含Unocss生成的样式
if grep -q 'uno-' dist/umi.css; then
  echo "Unocss styles generated successfully"
else
  echo "Unocss styles missing in production build"
  exit 1
fi