Umi项目构建冲突：Mako与Unocss样式失效的插件优先级解决方案

问题场景：从开发到生产的样式断层

周五下午，前端开发者小李正准备提交Umi项目的新版本。在开发环境中，他使用umi dev启动的页面样式完美呈现，按钮的圆角、弹性布局和间距都符合设计规范。然而，当执行umi build打包生产版本后，测试人员反馈页面布局完全错乱——按钮变成了原始的方形，卡片间距消失，整个页面仿佛回到了没有样式的原始状态。

"开发环境正常，生产环境异常"，这个经典问题让小李陷入沉思。他检查了Unocss的配置文件，确认preset-uno已经正确引入；查看构建日志，没有任何报错信息；甚至尝试删除node_modules重新安装依赖，但问题依旧存在。直到他打开浏览器开发者工具，才发现生产环境下的DOM元素上虽然保留着flex items-center等原子化类名，但对应的CSS规则完全缺失。

问题分析：编译流程中的隐形冲突

现象特征：环境差异的关键线索

深入对比开发与生产环境的构建过程，发现三个关键差异点：

1. 热更新机制：开发环境下，Unocss的热更新能实时生成样式
2. 构建目标：生产环境启用了代码压缩和Tree Shaking
3. 执行顺序：Mako打包流程可能在Unocss生成样式前已完成资源处理

这些差异指向一个核心问题：插件执行顺序。在Umi的插件系统中，不同插件的执行阶段决定了资源处理的先后顺序，而这正是导致原子化CSS在生产环境丢失的关键。

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

Umi框架采用基于阶段(stage)的插件执行模型，每个插件可以通过stage配置指定其执行时机。核心代码逻辑在packages/core/src/service/plugin.ts中实现，插件加载遵循"阶段优先、注册其次"的原则。

Mako作为Umi的官方构建工具，默认在较早的阶段（stage 0）执行资源打包流程。而Unocss需要在CSS处理阶段介入，将原子化类名转换为实际样式规则。当Mako的资源处理先于Unocss执行时，就会导致原始类名被打包，而原子化样式规则却未被生成。

冲突本质：资源处理的时间差

通过分析preset-umi的插件注册列表可以发现，Mako插件（features/mako/mako）默认注册在Unocss之前。这种顺序导致：

1. Mako首先处理所有资源文件，包括CSS
2. Unocss在后续阶段生成原子化样式
3. 生成的样式未能被Mako的打包流程捕获
4. 最终输出的CSS文件缺少关键样式规则

解决方案：插件优先级调整策略

诊断方法：确认插件执行顺序

在着手解决前，我们需要先通过Umi的检查命令确认当前插件顺序：

# 查看所有插件及其执行阶段
umi inspect plugins

在输出结果中查找Mako和Unocss相关插件，你可能会看到类似这样的顺序：

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

这表明Mako确实在Unocss之前执行，验证了我们的推测。

实施步骤：自定义插件优先级控制

1. 创建优先级控制插件

在项目根目录创建plugin-unocss-priority.ts文件，通过修改配置调整Unocss的执行阶段：

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

export default (api: IApi) => {
  // 在配置修改阶段调整插件顺序
  api.modifyConfig((memo) => {
    // 遍历插件列表找到Unocss插件
    memo.plugins = memo.plugins?.map(plugin => {
      // 处理字符串形式的插件配置
      if (typeof plugin === 'string' && plugin.includes('unocss')) {
        return {
          path: plugin,
          // 设置为最大安全整数，确保在所有插件之后执行
          stage: Number.MAX_SAFE_INTEGER 
        };
      }
      // 处理对象形式的插件配置
      if (typeof plugin === 'object' && plugin.path && plugin.path.includes('unocss')) {
        return {
          ...plugin,
          stage: Number.MAX_SAFE_INTEGER
        };
      }
      return plugin;
    });
    return memo;
  });
};

2. 配置文件注册与Unocss设置

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

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',
    // 确保生产环境不遗漏样式
    content: {
      filesystem: ['src/**/*.{ts,tsx,js,jsx}'],
    },
  },
  // 明确指定使用Mako作为构建工具
  bundler: 'mako',
});

3. 验证插件顺序调整结果

再次执行插件检查命令，确认Unocss现在在Mako之后执行：

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

正确的输出应显示：

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

验证策略：开发与生产环境双重测试

开发环境验证

启动开发服务器并检查样式生成情况：

umi dev

在浏览器中访问页面，使用开发者工具检查元素：

1. 选择一个应用了Unocss类名的元素（如flex justify-center）
2. 在Elements面板中确认该元素已应用转换后的哈希类名
3. 在Styles面板中验证对应的CSS规则是否存在

生产环境验证

构建生产版本并预览：

# 构建生产版本
umi build

# 启动本地预览服务器
umi preview

验证步骤：

1. 检查dist目录下的CSS文件（通常是umi.css）
2. 搜索原子化类名对应的哈希值，确认样式规则已生成
3. 测试页面交互，确保所有样式在生产环境正常工作

问题预防：长期维护策略

版本锁定与依赖管理

为避免因依赖版本更新导致的插件行为变化，建议在package.json中锁定关键依赖版本：

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

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

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

自动化测试集成

在CI/CD流程中添加样式验证步骤，确保构建产物包含Unocss生成的样式：

# 构建完成后检查CSS文件大小，确保不为空
test -s dist/umi.css && echo "CSS file generated successfully" || echo "CSS file missing!"

文档与团队协作

将插件顺序调整方案记录在项目文档中，并确保团队所有成员：

1. 理解Mako与Unocss的执行顺序原理
2. 掌握umi inspect plugins命令的使用方法
3. 遵循依赖版本锁定策略

总结

Mako与Unocss的样式冲突本质是插件执行顺序问题，通过自定义插件调整Unocss的执行阶段，我们可以确保原子化样式在资源打包前完成生成。这一解决方案的核心在于理解Umi的插件阶段模型，并利用stage配置项控制插件执行顺序。

关键启示：在Umi生态中，插件的执行顺序往往是解决构建问题的关键。当遇到开发/生产环境差异时，首先应检查插件顺序，而非怀疑配置错误。

通过本文介绍的"诊断-调整-验证"三步法，你可以系统地解决类似的插件协作问题，确保Umi项目在各种环境下的一致性表现。