Umi框架中Mako与Unocss集成的架构级解决方案：从冲突分析到环境适配

技术现象解析：开发/生产环境样式差异

在Umi项目中集成Mako构建工具与Unocss原子化CSS框架时，常出现"开发环境umi dev样式正常，生产环境umi build后样式丢失或布局错乱"的矛盾现象。这种环境差异本质是Mako资源打包流程与Unocss样式生成阶段的执行顺序冲突导致的原子化CSS处理失效问题。

底层执行逻辑：编译流程冲突原理

冲突触发条件

1. Mako作为bundler在默认配置下优先执行资源打包
2. Unocss插件在样式处理阶段后于Mako执行
3. 生产环境压缩优化导致未处理的原子类名被直接打包

Umi插件执行流程图

Umi框架的插件执行顺序由Plugin类控制，遵循"注册优先"原则。从preset-umi的插件注册列表可见，Mako插件（features/mako/mako）默认注册于Unocss之前，导致Unocss生成的原子化样式无法被Mako的打包流程捕获。

分层解决方案：从配置到验证

配置干预层

1. 创建Unocss优先级控制插件

在项目根目录创建plugin-unocss-priority.ts：

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

export default (api: IApi) => {
  // 修改Unocss插件执行阶段
  api.modifyConfig((memo) => {
    memo.plugins = memo.plugins?.map(plugin => {
      // 识别Unocss插件并设置最高执行优先级
      if (typeof plugin === 'string' && plugin.includes('unocss')) {
        return {
          path: plugin,
          // 设置为Number.MAX_SAFE_INTEGER确保最后执行
          stage: Number.MAX_SAFE_INTEGER
        };
      }
      return plugin;
    });
    return memo;
  });
};

2. 完整配置文件示例

修改.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',
  },
  // 明确指定Mako作为构建工具
  bundler: 'mako',
  // 其他项目配置...
  routes: [/* ... */],
});

验证指令：执行umi inspect config检查插件配置是否生效

系统验证层

1. 插件加载顺序验证

# 检查插件加载顺序
umi inspect plugins | grep -E 'mako|unocss'

正确输出应显示Unocss插件位于Mako之后：

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

2. 样式生成验证

# 构建并检查CSS输出
umi build && grep -r 'unocss' dist/umi.css

风险提示：若未找到unocss相关样式，需检查Unocss配置中的content字段是否正确包含了所有需要处理的文件路径。

环境适配层

Node.js版本兼容处理

不同Node版本下的依赖解析差异可能影响构建结果：

Node版本	兼容处理方案
v14.x	需安装abort-controller polyfill
v16.x	需设置NODE_OPTIONS=--openssl-legacy-provider
v18.x+	原生支持，无需额外配置

验证指令：node -v && umi build确认构建过程无兼容性警告

验证体系：全环境一致性保障

开发环境验证

umi dev

使用浏览器开发者工具检查元素类名，确认原子化类（如flex items-center）已被转换为Unocss生成的哈希类名。

生产环境验证

umi build && umi preview

检查dist/umi.css文件应包含Unocss生成的原子化样式规则，且页面布局与开发环境一致。

问题反馈与案例资源

• 问题反馈路径：项目issue提交：packages/core/
• 相关案例库：参考examples/with-unocss/项目完整配置

通过以上架构级解决方案，可彻底解决Mako与Unocss的编译顺序冲突，确保原子化样式在各环境下的一致性表现。