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

当你在Umi项目中同时集成Mako构建工具和Unocss原子化CSS框架时，是否遇到过这样的情况：开发环境下样式显示正常，可一旦执行umi build构建生产版本，页面布局就变得错乱不堪？这种"开发正常，生产异常"的现象往往与工具链的执行顺序密切相关。本文将带你从问题定位到原理剖析，最终通过两种实现路径彻底解决这一棘手问题。

诊断环境差异：从现象到本质

识别典型症状

当Mako与Unocss配合出现问题时，通常会表现出以下特征：

• 🔧 开发环境：umi dev启动后，所有Unocss原子化类（如flex items-center justify-between）都能正确生效
• ⚠️ 生产环境：执行umi build后，部分或全部原子化样式丢失，浏览器控制台可能出现"未找到类名"的警告
• 📱 表现差异：同一套代码在开发和生产环境呈现不同效果，且问题集中在CSS样式层面

初步环境检查

在深入解决前，请先确认你的环境配置：

1. 检查package.json中Umi版本是否为3.5.0以上
2. 确认已安装@umijs/plugin-unocss和@umijs/bundler-mako依赖
3. 执行umi -v查看当前工具链版本信息

原理剖析：编译流程的隐形冲突

构建流程可视化

Umi的插件执行顺序决定了资源处理的先后关系，以下是Mako与Unocss冲突时的流程图：

这个流程图展示了Umi框架的基本架构，虽然没有直接显示插件执行顺序，但可以帮助我们理解为什么插件顺序如此重要。在默认配置下，Mako作为bundler会优先处理资源，导致Unocss生成的原子化样式无法被正确捕获。

底层原理延伸

Umi插件系统基于stage机制和生命周期钩子工作：

• stage机制：每个插件可以通过设置stage值（数字类型）来决定执行顺序，值越小越早执行
• 生命周期钩子：Umi在构建过程中会触发一系列钩子（如onStart、onBuildComplete等），插件通过注册这些钩子参与构建流程

Mako作为官方推荐的bundler，默认stage值较低（约0-100），而Unocss插件如果没有特别设置，会在较晚阶段执行，导致其生成的样式无法被Mako的打包流程捕获。

分步解决方案：从快速修复到工程化实现

问题复现：构建最小测试环境

为了确保解决方案有效，我们先创建一个最小化的测试环境：

# 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/um/umi
cd umi/examples/with-unocss

# 安装依赖
pnpm install

# 启动开发环境（此时样式应正常）
pnpm dev

# 构建生产版本（此时样式应丢失）
pnpm build && pnpm preview

[!WARNING] 常见误区：不要依赖umi build --watch进行调试，该命令可能会改变插件执行顺序，导致问题无法复现。

解决方案一：快速修复版（适合新手）

这种方式通过直接修改配置文件，快速调整插件执行顺序：

1. 修改.umirc.ts配置

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

export default defineConfig({
  plugins: [
    // 调整Unocss插件位置到最后
    '@umijs/plugin-unocss',
  ],
  unocss: {
    ...unocssConfig,
    // 强制Unocss在构建阶段生成样式
    envMode: 'build',
  },
  bundler: 'mako',
  // 添加插件执行顺序配置
  pluginPriority: {
    '@umijs/plugin-unocss': 10000, // 设置一个较大的值确保后执行
  },
});

2. 验证插件顺序

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

正确的输出应显示Unocss插件在Mako之后：

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

[!WARNING] 常见误区：pluginPriority配置仅在Umi 3.5.0+版本可用，旧版本需要通过其他方式调整。

解决方案二：工程化版（适合团队项目）

对于团队协作项目，建议采用更工程化的方式，将配置逻辑封装为独立插件：

1. 创建优先级控制插件

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

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

/**
 * 调整Unocss插件执行顺序的辅助插件
 * 确保Unocss在Mako之后执行
 */
export default function unocssPriorityPlugin(api: IApi) {
  // 在配置准备阶段修改插件顺序
  api.onStart(() => {
    const unocssPluginIndex = api.config.plugins?.findIndex(
      plugin => typeof plugin === 'string' && plugin.includes('unocss')
    );
    
    if (unocssPluginIndex > -1 && api.config.plugins) {
      // 将Unocss插件移到最后
      const [unocssPlugin] = api.config.plugins.splice(unocssPluginIndex, 1);
      api.config.plugins.push(unocssPlugin);
      
      // 记录调整日志
      api.logger.info('✅ Unocss插件已移至最后执行');
    }
  });
}

2. 在配置中注册插件

修改.umirc.ts：

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

export default defineConfig({
  plugins: [
    './config/plugin-unocss-priority', // 先注册优先级控制插件
    '@umijs/plugin-unocss',
  ],
  unocss: {
    ...unocssConfig,
    envMode: 'build',
  },
  bundler: 'mako',
});

效果验证：从手动测试到自动化保障

手动验证流程

✅ 开发环境验证：

umi dev

访问页面，使用浏览器开发者工具检查元素，确认原子化类名已被正确转换为哈希类名。

✅ 生产环境验证：

umi build && umi preview

检查生成的CSS文件（位于dist/umi.css），应包含Unocss生成的原子化样式规则。

自动化测试建议

为避免未来升级时问题复发，建议添加E2E测试用例：

1. 创建cypress/e2e/unocss.spec.ts：

describe('Unocss样式生成测试', () => {
  it('应该正确生成原子化样式', () => {
    cy.visit('/');
    // 检查一个使用了Unocss原子类的元素
    cy.get('.flex.items-center')
      .should('have.css', 'display', 'flex')
      .and('have.css', 'align-items', 'center');
  });
});

2. 在package.json中添加测试脚本：

"scripts": {
  "test:unocss": "cypress run --spec 'cypress/e2e/unocss.spec.ts'"
}

长期维护策略

1. 版本锁定：在package.json中锁定关键依赖版本：

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

2. 定期同步：使用项目中的scripts/syncMako.ts脚本同步最新构建工具版本：

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

3. 文档更新：在项目README.md中添加"样式构建注意事项"章节，记录解决此问题的配置步骤。

总结与延伸思考

解决Mako与Unocss的编译顺序冲突，核心在于理解Umi插件系统的stage机制和生命周期钩子。通过本文介绍的两种解决方案，你可以根据项目规模和团队情况选择合适的实现方式：

• 快速修复版：适合个人项目或紧急修复，通过直接修改配置快速解决问题
• 工程化版：适合团队协作项目，将配置逻辑封装为插件，提高代码可维护性

Umi作为React生态中的重要框架，其插件系统设计灵活但也带来了配置复杂度。理解插件执行顺序和生命周期，将帮助你更好地应对各类构建工具集成挑战。

最后，当你在Umi项目中集成其他CSS解决方案（如Tailwind CSS、Styled Components等）时，也可以借鉴本文的思路，通过调整插件执行顺序来解决潜在的工具链冲突问题。