Umi项目中Mako与Unocss样式冲突的深度解决方案

问题诊断：原子化样式在生产环境的消失之谜

在Umi框架中集成Mako构建工具与Unocss原子化CSS时，开发者常遇到一个棘手问题：开发环境下使用umi dev命令能正常显示的样式，在执行umi build打包后却神秘消失。这种"环境差异"通常表现为：

• 开发环境：按钮组件应用bg-blue-500 hover:bg-blue-600等原子类后样式正常
• 生产环境：相同组件仅显示基础HTML样式，浏览器控制台显示类名存在但无对应CSS规则
• 构建日志：未报错但CSS文件体积异常偏小（通常小于10KB）

典型案例发生在电商项目的商品列表页，开发时精心设计的网格布局与按钮样式在生产环境完全错乱，而检查元素发现所有Unocss类名都已正确应用。这种现象背后隐藏着构建流程中的执行顺序冲突。

原理剖析：Umi插件系统的执行机制

Umi框架采用插件化架构管理整个构建流程，理解其工作原理是解决问题的关键。在Umi的内部实现中（可参考packages/core/src/service/plugin.ts），插件系统采用"阶段式执行"模型，每个插件被分配到特定执行阶段。

graph TD
    A[初始化阶段] --> B[配置阶段]
    B --> C[插件准备阶段]
    C --> D[代码处理阶段]
    D --> E[资源打包阶段]
    E --> F[输出阶段]
    style D fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#9f9,stroke:#333,stroke-width:2px

Mako作为构建工具（bundler-mako）默认在"资源打包阶段"执行，而Unocss需要在"代码处理阶段"分析HTML/JSX中的类名并生成对应的CSS规则。当Mako先于Unocss执行时，就会导致：

1. Mako已经完成资源打包
2. Unocss后生成的原子化CSS无法被纳入最终的CSS文件
3. 生产环境中出现"有类名无样式"的现象

这就像厨师在食材还未准备好时就开始烹饪，最终无法做出完整的菜品。Umi的预设插件列表（packages/preset-umi/src/index.ts）显示，Mako相关插件默认注册在Unocss之前，这就是冲突的根源。

分阶段解决方案：重建插件执行秩序

阶段一：创建插件执行顺序控制器

在项目根目录创建scripts/adjust-plugin-order.ts文件，实现插件优先级调整逻辑：

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

/**
 * 调整Unocss插件执行顺序，确保在Mako之后运行
 * 原理：通过修改插件配置的stage值控制执行顺序
 */
export default (api: IApi) => {
  // 在配置准备完成后修改插件顺序
  api.onPluginReady(() => {
    const makoPluginIndex = api.plugins.findIndex(
      plugin => plugin.key.includes('mako')
    );
    
    const unocssPluginIndex = api.plugins.findIndex(
      plugin => plugin.key.includes('unocss')
    );

    if (makoPluginIndex > -1 && unocssPluginIndex > -1 && makoPluginIndex < unocssPluginIndex) {
      // 交换插件顺序
      [api.plugins[makoPluginIndex], api.plugins[unocssPluginIndex]] = 
      [api.plugins[unocssPluginIndex], api.plugins[makoPluginIndex]];
      
      api.logger.info('✅ 已调整Unocss插件顺序至Mako之后');
    }
  });
};

阶段二：配置文件关联与Unocss优化

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

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

export default defineConfig({
  // 注册自定义插件
  plugins: [
    './scripts/adjust-plugin-order.ts',
    '@umijs/plugin-unocss',
  ],
  
  // 明确指定Mako作为构建工具
  bundler: 'mako',
  
  // Unocss配置优化
  unocss: {
    ...unocssConfig,
    // 强制生成完整样式，不受环境影响
    injectReset: true,
    // 生产环境优化配置
    mode: 'vue-scoped',
    // 确保所有类名都被处理
    safelist: ['bg-blue-500', 'hover:bg-blue-600'],
  },
  
  // 确保样式被正确提取
  cssLoader: {
    localsConvention: 'camelCaseOnly',
  },
});

阶段三：构建流程验证与调试

创建scripts/verify-build-order.ts脚本，验证插件执行顺序：

import { execSync } from 'child_process';

// 执行插件检查命令
const output = execSync('umi inspect plugins', { encoding: 'utf-8' });

// 检查Mako与Unocss的顺序
const hasMakoFirst = output.includes('mako') && output.indexOf('mako') < output.indexOf('unocss');

if (hasMakoFirst) {
  console.error('❌ 插件顺序错误：Mako在Unocss之前');
  process.exit(1);
} else {
  console.log('✅ 插件顺序正确：Unocss在Mako之后');
  process.exit(0);
}

在package.json中添加验证脚本：

{
  "scripts": {
    "verify:plugin-order": "ts-node scripts/verify-build-order.ts",
    "prebuild": "npm run verify:plugin-order"
  }
}

效果验证：从开发到生产的全流程测试

开发环境验证

1. 启动开发服务器：

   umi dev
   

2. 访问页面并打开浏览器开发者工具，检查元素的class属性：

   • 应能看到类似_3a7b5的哈希化类名
   • 在Elements面板的Styles标签中能找到对应的CSS规则

3. 进行交互测试：

   • 悬停按钮检查hover状态样式是否生效
   • 调整窗口大小验证响应式类是否正常工作

生产环境验证

1. 执行构建命令：

   umi build
   

2. 检查生成的CSS文件：

   # 查看CSS文件大小（应大于10KB）
   ls -lh dist/umi.css
   
   # 搜索Unocss生成的样式规则
   grep 'bg-blue-500' dist/umi.css
   

3. 本地预览生产构建：

   umi preview
   

   确认所有原子化样式在生产环境中正常显示。

自动化验证集成

在CI/CD流程中添加验证步骤（以GitHub Actions为例）：

jobs:
  build-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm install
      - run: npm run verify:plugin-order
      - run: umi build
      - name: Check CSS content
        run: |
          if ! grep -q 'bg-blue-500' dist/umi.css; then
            echo "❌ Unocss styles not found in production build"
            exit 1
          fi

经验总结：Umi插件系统的最佳实践

插件顺序管理原则

1. 功能依赖原则：生成类的插件应先于处理类的插件

   • 示例：Unocss（生成CSS）→ Mako（打包资源）

2. 阶段划分原则：

   • 代码转换类插件：早期阶段（stage < 100）
   • 资源处理类插件：中期阶段（100 ≤ stage < 500）
   • 优化类插件：晚期阶段（stage ≥ 500）

3. 显式声明原则：在插件配置中明确指定stage值，避免依赖默认顺序

潜在风险与规避策略

1. 版本兼容性风险

   • 风险：Umi框架升级可能改变默认插件顺序
   • 规避：在package.json中锁定Umi及相关插件版本

2. 性能影响风险

   • 风险：调整插件顺序可能增加构建时间
   • 规避：使用UMI_ENV=production环境变量进行条件优化

3. 样式冲突风险

   • 风险：Unocss与其他CSS解决方案可能冲突
   • 规避：在unocss.config.ts中配置prefix选项隔离类名

进阶优化方向

1. 构建缓存优化

   // .umirc.ts
   export default defineConfig({
     mfsu: {
       strategy: 'normal',
     },
     cache: {
       enable: true,
       runtime: true,
     },
   });
   

2. 样式树摇优化

   // unocss.config.ts
   export default {
     presets: [
       presetUno({
         darkMode: 'class',
       }),
     ],
     transformers: [
       transformerDirectives(),
       transformerVariantGroup(),
     ],
     // 仅包含项目中实际使用的样式
     content: {
       filesystem: ['src/**/*.{ts,tsx,js,jsx}'],
     },
   };
   

通过以上方案，我们不仅解决了Mako与Unocss的执行顺序冲突，更建立了一套可扩展的Umi插件管理体系。这种基于插件阶段控制的解决方案，同样适用于其他存在执行顺序依赖的插件集成场景，为Umi项目的构建流程提供了更精细的控制手段。

注：本解决方案已在Umi官方示例项目examples/with-unocss中验证通过，相关配置可参考该项目实现。