Umi框架中Mako与Unocss协同问题的创新解决方法

在Umi框架开发中，开发者常遇到这样的困境：使用Mako构建工具与Unocss原子化CSS框架时，开发环境样式正常，生产环境却出现样式丢失。这一现象的核心在于Umi框架、构建流程冲突与插件优先级调整方案三者之间的复杂关系。本文将系统讲解如何通过调整插件执行顺序，解决这一跨环境样式一致性问题。

诊断：构建流程中的隐形冲突

当umi dev显示正常而umi build出现样式错乱时，问题往往隐藏在构建工具的执行顺序中。Mako作为Umi的默认构建工具，负责资源打包流程；Unocss则需要在CSS处理阶段动态生成原子化样式。就像餐厅厨房中，若配菜流程（Unocss）在烹饪（Mako）之后才完成，最终菜品自然缺少关键配料。

Umi的插件系统采用"注册优先"原则，在默认配置下，Mako插件会先于Unocss执行。这导致Unocss生成的原子化样式无法被Mako的打包流程捕获，最终生产环境中出现样式缺失。通过umi inspect plugins命令可以清晰看到插件的加载顺序，这是诊断此类问题的关键第一步。

剖析：插件执行机制的技术原理

Umi框架的插件执行机制类似于工厂的流水线作业，每个插件如同一个加工环节，必须按照特定顺序执行才能保证最终产品质量。Umi的Plugin类控制着这一流程，通过stage参数决定插件的执行时机，数值越小执行越早。

图1：Umi插件执行流程示意图，展示了Mako与Unocss在默认配置和优化配置下的执行顺序对比

在标准流程中，Mako（stage 0）先处理资源，Unocss（默认stage）后生成样式，导致样式无法被正确打包。解决方案的核心是调整Unocss的stage参数，使其在Mako之后执行，确保原子化样式被纳入打包流程。这就像调整流水线顺序，让配料环节在烹饪前完成。

实施：分阶段配置优化方案

阶段一：创建优先级控制插件

在项目根目录创建unocss-priority-plugin.ts文件，通过修改插件配置调整执行顺序：

import { IApi } from '@umijs/types';

export default (api: IApi) => {
  // 调整Unocss插件执行阶段
  api.modifyConfig((config) => {
    config.plugins = config.plugins?.map(pluginItem => {
      if (typeof pluginItem === 'string' && pluginItem.includes('unocss')) {
        return {
          path: pluginItem,
          // 设置为最大安全整数确保最后执行
          stage: Number.MAX_SAFE_INTEGER
        };
      }
      return pluginItem;
    });
    return config;
  });
};

阶段二：配置文件集成与验证

修改.umirc.ts文件，集成自定义插件并配置Unocss：

import { defineConfig } from 'umi';
import unocssSettings from './unocss.config';

export default defineConfig({
  plugins: [
    './unocss-priority-plugin.ts',
    '@umijs/plugin-unocss',
  ],
  unocss: {
    ...unocssSettings,
    // 强制生产环境样式生成
    envMode: 'production',
  },
  bundler: 'mako',
});

执行umi inspect plugins | grep -E 'mako|unocss'命令验证顺序，确保Unocss出现在Mako之后。

验证：多环境一致性测试

开发环境验证

umi dev

访问应用并使用浏览器开发者工具检查元素，确认原子化类名（如flex justify-center）已正确应用。

生产环境验证

umi build && umi preview

检查dist/umi.css文件，应包含Unocss生成的原子化样式规则。重点验证动态生成的类名是否存在于CSS文件中。

⚠️ 注意事项：测试时应清除浏览器缓存，避免旧样式干扰验证结果。建议使用隐私模式进行测试，确保看到的是最新构建结果。

拓展：构建优化的进阶实践

版本锁定策略

在package.json中明确锁定Mako版本，避免自动更新导致的兼容性问题：

"dependencies": {
  "@umijs/bundler-mako": "1.2.3"
}

自动化同步脚本

使用项目中的scripts/syncMako.ts脚本定期同步官方最新版本：

ts-node scripts/syncMako.ts --version 1.2.3

延伸思考

1. 在大型项目中，如何平衡插件执行顺序与构建性能？是否存在最优的插件执行序列？
2. 除了调整stage参数，还有哪些方法可以控制Umi插件的执行顺序？它们各自的适用场景是什么？

通过以上方法，我们不仅解决了Mako与Unocss的协同问题，更深入理解了Umi插件系统的工作原理，为应对复杂构建场景提供了可扩展的解决方案。这种插件优先级调整的思路，同样适用于其他存在执行顺序冲突的插件组合场景。