Umi框架中Mako与Unocss集成：攻克原子化样式编译顺序冲突的终极解决方案

在Umi框架项目开发中，同时集成Mako构建工具与Unocss原子化CSS框架时，常出现开发环境样式正常但生产环境样式丢失或错乱的问题。这一现象严重影响开发效率与用户体验，其核心原因在于Mako与Unocss的编译顺序冲突，导致原子化样式未能被正确处理。本文将从问题诊断入手，深入分析技术原理，提供两种解决方案，并指导效果验证与最佳实践，助你彻底解决这一技术难题。

现象描述

在Umi项目中使用Mako作为构建工具并集成Unocss后，开发环境下通过umi dev命令运行时，页面样式显示正常，原子化类名能正确生效。然而，执行umi build打包部署到生产环境后，页面布局错乱，部分原子化样式消失，浏览器开发者工具检查发现Unocss生成的原子类未被正确包含在最终的CSS文件中。这种开发与生产环境的样式差异，严重阻碍项目交付进度。

技术原理

Umi框架架构

Umi是一个基于React的企业级前端框架，采用插件化架构设计，通过插件系统管理整个构建流程。其核心架构包括核心服务、插件系统、构建工具等模块，各模块协同工作完成项目的开发、构建与部署。

核心概念解析

技术定义	类比说明
原子化CSS	一种按需生成CSS类的技术方案，每个类对应一个具体的CSS样式规则，如flex对应display: flex
Mako	Umi官方推荐的构建工具，负责代码打包、资源处理等构建流程
插件执行阶段	Umi插件系统中定义的插件执行顺序，通过stage属性控制，数值越大执行越晚

官方源码分析

Umi的插件执行顺序由packages/core/src/service/plugin.ts文件中的Plugin类控制。关键代码片段如下：

// packages/core/src/service/plugin.ts
export class Plugin {
  // ...
  constructor(public api: IApi, public opts: IPluginOpts) {
    // 插件默认stage为0
    this.stage = opts.stage ?? 0;
  }
  // ...
}

从代码可知，插件的stage属性决定执行顺序，默认值为0，数值越大执行越晚。在packages/preset-umi/src/index.ts的插件注册列表中，Mako插件（features/mako/mako）默认注册在Unocss插件之前，导致Unocss生成的原子化样式无法被Mako的打包流程捕获。

冲突分析

Mako与Unocss的编译顺序冲突可通过以下流程图清晰展示：

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尚未生成原子化样式
    Unocss Plugin->>CSS Processing: 生成原子化样式(默认stage 0，晚于Mako)
    CSS Processing-->>Umi Core: 输出缺少原子类的CSS

从流程图可以看出，由于Mako和Unocss默认都在stage 0执行，但Mako先于Unocss注册，导致Mako在Unocss生成原子化样式之前就已经完成了CSS处理，使得Unocss生成的样式无法被纳入最终的CSS文件。

实施步骤

基础版解决方案：调整插件stage值

🔧 步骤1：创建插件优先级配置文件 在项目根目录创建plugin-unocss-priority.ts文件：

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

export default (api: IApi) => {
  // 设置Unocss在Mako之后执行
  api.modifyConfig((memo) => {
    memo.plugins = memo.plugins?.map(plugin => 
      typeof plugin === 'string' && plugin.includes('unocss') 
        ? { 
            path: plugin,
            // 关键：设置较晚的执行阶段
            stage: 100 
          } 
        : plugin
    );
    return memo;
  });
};

⚠️ 注意：修改配置前建议备份原配置文件，以防配置错误导致项目无法运行。

🔧 步骤2：修改.umirc.ts配置

// 项目根目录/.umirc.ts
import { defineConfig } from 'umi';
import unocssConfig from './unocss.config';

export default defineConfig({
  plugins: [
    './plugin-unocss-priority.ts',
    '@umijs/plugin-unocss',
  ],
  unocss: {
    ...unocssConfig,
    // 强制启用生产环境生成
    envMode: 'build',
  },
  // 确保Mako作为bundler
  bundler: 'mako',
});

进阶版解决方案：自定义插件排序逻辑

🔧 步骤1：创建高级插件配置文件

// 项目根目录/plugin-unocss-advanced.ts
import { IApi } from '@umijs/types';

export default (api: IApi) => {
  api.modifyPlugins((plugins) => {
    // 找到Mako和Unocss插件的索引
    const makoIndex = plugins.findIndex(p => 
      (typeof p === 'string' && p.includes('mako')) || 
      (typeof p === 'object' && p.path?.includes('mako'))
    );
    const unocssIndex = plugins.findIndex(p => 
      (typeof p === 'string' && p.includes('unocss')) || 
      (typeof p === 'object' && p.path?.includes('unocss'))
    );

    if (makoIndex > -1 && unocssIndex > -1 && makoIndex < unocssIndex) {
      // 交换插件顺序
      [plugins[makoIndex], plugins[unocssIndex]] = [plugins[unocssIndex], plugins[makoIndex]];
    }

    return plugins;
  });
};

💡 专家建议：进阶版方案通过直接调整插件数组顺序，比基础版的stage设置具有更高的优先级，适用于复杂的插件依赖场景。

🔧 步骤2：更新.umirc.ts配置

// 项目根目录/.umirc.ts
import { defineConfig } from 'umi';
import unocssConfig from './unocss.config';

export default defineConfig({
  plugins: [
    './plugin-unocss-advanced.ts',
    '@umijs/plugin-unocss',
    // Mako插件会被自动排序到Unocss之后
  ],
  unocss: {
    ...unocssConfig,
    envMode: 'build',
  },
  bundler: 'mako',
});

效果验证

📊 开发环境验证

1. 执行umi dev启动开发服务器
2. 访问页面，使用浏览器开发者工具检查元素
3. 确认原子化类名（如flex items-center）已被正确转换为哈希类名
4. 修改原子化类名，观察页面样式是否实时更新

📊 生产环境验证

1. 执行umi build构建生产版本
2. 运行umi preview预览生产构建结果
3. 检查dist/umi.css文件，确认包含Unocss生成的原子化样式规则
4. 对比开发环境与生产环境的页面样式，确保一致性

最佳实践

版本控制建议

在package.json中锁定Mako和Unocss相关依赖的版本：

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

定期运行pnpm update @umijs/bundler-mako @umijs/plugin-unocss unocss更新依赖，并进行充分测试。

配置管理

将Unocss配置独立为unocss.config.ts文件，便于维护：

// 项目根目录/unocss.config.ts
import { defineConfig } from 'unocss';

export default defineConfig({
  rules: [
    // 自定义规则
  ],
  presets: [
    // 预设配置
  ],
});

常见失败场景排查

1. 场景一：插件优先级未生效

   • 症状：执行umi inspect plugins发现Unocss仍在Mako之前
   • 解决：检查自定义插件文件路径是否正确，确保在.umirc.ts的plugins数组中排在Unocss插件之前

2. 场景二：生产环境样式仍丢失

   • 症状：开发环境正常，生产环境样式缺失
   • 解决：确认Unocss配置中的envMode是否设置为'build'，确保生产环境强制生成样式

3. 场景三：插件冲突导致构建失败

   • 症状：调整插件顺序后出现构建错误
   • 解决：减少stage值的差距（如从100改为10），或使用进阶版的插件排序方案

相关问题

Q1: Umi中如何查看所有插件的执行顺序？ A1: 执行umi inspect plugins命令，可列出所有插件及其stage值，帮助确认插件执行顺序。

Q2: Unocss的原子化样式在生产环境被压缩后如何调试？ A2: 在unocss.config.ts中设置sourceMap: process.env.NODE_ENV === 'development'，开发环境生成source map便于调试，生产环境关闭以减小体积。

Q3: Mako与Webpack构建工具相比，在处理Unocss时有哪些优势？ A3: Mako作为Umi官方推荐的新一代构建工具，具有更快的构建速度和更好的Tree-shaking能力，能更高效地处理Unocss生成的原子化样式，减少最终CSS体积。

通过本文介绍的解决方案，你可以彻底解决Umi框架中Mako与Unocss的编译顺序冲突问题，确保原子化样式在开发与生产环境中都能稳定生效。无论是基础版的stage调整还是进阶版的插件排序，都能帮助你构建出高效、稳定的前端应用。遵循最佳实践，定期更新依赖并进行充分测试，将进一步提升项目的可维护性和稳定性。