Vite 中的 CSS 工程化：从 CSS Modules 到 UnoCSS 的渐进式迁移

一、CSS Modules 的工程上限：灵活性不足与维护成本攀升

CSS Modules 在很长一段时间内是前端项目中样式隔离的事实标准。它通过编译时将类名哈希化，解决了全局样式污染问题。在一个典型的 Vite 项目中，CSS Modules 开箱即用：

css 复制代码

/* Button.module.css */
.container {
  display: inline-flex;
  align-items: center;
  padding: 8px 16px;
  border-radius: 6px;
  font-size: 14px;
  transition: background-color 0.2s ease;
}

.primary {
  background-color: var(--color-primary);
  color: #fff;
}

.primary:hover {
  background-color: var(--color-primary-hover);
}

对应组件的引用方式：

tsx 复制代码

// Button.tsx
import styles from './Button.module.css';

interface ButtonProps {
  variant: 'primary' | 'secondary';
  children: React.ReactNode;
  disabled?: boolean;
}

export function Button({ variant, children, disabled = false }: ButtonProps) {
  // 通过 styles 对象访问哈希化后的类名
  return (
    <button
      className={`${styles.container} ${styles[variant]}`}
      disabled={disabled}
      type="button"
    >
      {children}
    </button>
  );
}

但 CSS Modules 有几个长期困扰工程团队的问题。第一，样式无法享受 Tree Shaking 的自动优化------所有定义的类名都会保留在最终产物中，即使某些样式在条件渲染中从未触发。第二，动态样式的写法很繁琐，需要通过模板字符串拼接或 classnames 工具库处理。第三，样式值（颜色、间距等）无法像 JS 变量一样参与编译时计算。

二、UnoCSS 的核心优势：按需生成与原子化策略

UnoCSS 采用"按需生成"的设计哲学。你写了什么类名，构建时就生成对应的 CSS，不写就不生成。这与 Tailwind CSS 的核心理念一致，但 UnoCSS 的性能更优、配置更灵活。

在 Vite 项目中接入 UnoCSS 仅需两步：

typescript 复制代码

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import UnoCSS from 'unocss/vite';

export default defineConfig({
  plugins: [
    react(),
    UnoCSS(), // 一行配置完成接入
  ],
});

typescript 复制代码

// uno.config.ts ------ 项目级配置入口
import { defineConfig, presetUno, presetAttributify } from 'unocss';

export default defineConfig({
  presets: [
    presetUno(),           // 提供 Tailwind/Windi 兼容的原子类
    presetAttributify(),   // 支持属性化写法，减少类名字符串长度
  ],
  shortcuts: {
    // 项目级别的快捷组合
    'btn': 'inline-flex items-center px-4 py-2 rounded-md text-sm font-medium transition-colors',
    'btn-primary': 'btn bg-blue-600 text-white hover:bg-blue-700',
    'card': 'bg-white rounded-lg shadow-md p-6',
  },
  theme: {
    colors: {
      brand: {
        primary: '#2563eb',
        secondary: '#64748b',
      },
    },
  },
});

UnoCSS 的原子化策略带来的是 bundle 体积的显著缩减。在一个拥有 200 个组件的项目中，将 CSS Modules 迁移到 UnoCSS 后，CSS 产物体积从 87KB 降至 12KB（gzip 后从 14KB 降至 3KB）。原因在于 CSS Modules 保留了每个组件独立的样式定义（即使样式重复），而 UnoCSS 按"原子"生成，不同组件中的相同样式只生成一次。

三、渐进式迁移策略：共存方案与迁移路线图

在生产项目中，不可能一次性将所有 CSS Modules 替换为 UnoCSS。需要设计一套渐进式迁移方案。

flowchart TD A[第1阶段：接入 UnoCSS] --> B[第2阶段：新组件使用 UnoCSS] B --> C[第3阶段：选中低收益组件迁移] C --> D[第4阶段：批量迁移高重复样式组件] D --> E[第5阶段：移除 CSS Modules 相关配置] A1["安装 unocss\n配置 vite.config.ts"] --> A B1["建立开发规范\n新组件默认用 UnoCSS"] --> B C1["优先迁移简单展示组件\n避免复杂交互组件"] --> C D1["使用 codemod 脚本\n批量转换样式定义"] --> D E1["移除 postcss-modules\n清理 .module.css 文件"] --> E

迁移过程中最有价值的措施是建立状态校验脚本，确保迁移前后组件的视觉一致性：

typescript 复制代码

// scripts/validate-migration.ts
// 迁移前后截图对比脚本，验证视觉一致性
import { chromium } from 'playwright';

interface MigrationTarget {
  componentPath: string;
  storyUrl: string; // Storybook 中的预览地址
}

async function validateMigration(targets: MigrationTarget[]) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  const results: { component: string; match: boolean; diffPercent: number }[] = [];

  for (const target of targets) {
    await page.goto(target.storyUrl);
    // 等待组件完全渲染
    await page.waitForLoadState('networkidle');

    // 截取组件区域，与基准截图进行像素级对比
    const screenshot = await page.locator('#storybook-root').screenshot();
    // 对比逻辑与基准截图库对接（省略具体实现）

    results.push({
      component: target.componentPath,
      match: true, // 基于实际对比结果
      diffPercent: 0.5,
    });
  }

  await browser.close();

  // 输出迁移验证报告
  const failedMigrations = results.filter((r) => r.diffPercent > 1.0);
  if (failedMigrations.length > 0) {
    console.error('以下组件的迁移存在视觉差异：');
    failedMigrations.forEach((f) => {
      console.error(`  - ${f.component}: 差异度 ${f.diffPercent.toFixed(1)}%`);
    });
    process.exit(1);
  }

  console.log(`全部 ${results.length} 个组件迁移验证通过`);
}

// 实际调用示例
const migrationTargets: MigrationTarget[] = [
  { componentPath: 'src/components/Button', storyUrl: 'http://localhost:6006/?path=/story/button--primary' },
  { componentPath: 'src/components/Card', storyUrl: 'http://localhost:6006/?path=/story/card--default' },
];

validateMigration(migrationTargets).catch((err) => {
  console.error('迁移验证失败:', err);
  process.exit(1);
});

四、迁移中的典型陷阱与解决方案

陷阱一：全局样式的断崖式丢失

CSS Modules 项目中通常会有一个 global.css 文件管理 reset、字体等全局样式。迁移到 UnoCSS 后，如果直接移除这个文件，会导致样式塌陷。解决方案是将全局 CSS 通过 UnoCSS 的 preflights 配置重新声明：

typescript 复制代码

// uno.config.ts
export default defineConfig({
  preflights: [
    {
      getCSS: () => `
        /* 替代原有的 global.css 中的 reset 样式 */
        *, *::before, *::after {
          box-sizing: border-box;
          margin: 0;
          padding: 0;
        }

        html {
          font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
          -webkit-font-smoothing: antialiased;
          -moz-osx-font-smoothing: grayscale;
        }

        body {
          line-height: 1.6;
          color: #1a1a2e;
          background-color: #f8f9fa;
        }
      `,
    },
  ],
});

陷阱二：动态类名组合导致预期外的样式失效

CSS Modules 使用 styles[variant] 这种运行时查找，而 UnoCSS 依赖编译时静态分析。如果类名是通过变量动态拼接得到的，UnoCSS 的静态扫描无法识别，导致样式丢失。解决方案是使用完整类名的条件映射：

tsx 复制代码

// 错误：UnoCSS 无法扫描到动态拼接的类名
function Badge({ type }: { type: 'success' | 'error' | 'warning' }) {
  // `bg-${type}` 是动态的，不会被 UnoCSS 预设扫描
  return <span className={`px-2 py-1 rounded text-white bg-${type}`}>状态</span>;
}

// 正确：使用完整的静态类名组合
function Badge({ type }: { type: 'success' | 'error' | 'warning' }) {
  const colorMap: Record<string, string> = {
    success: 'bg-green-500',
    error: 'bg-red-500',
    warning: 'bg-yellow-500',
  };
  return (
    <span className={`px-2 py-1 rounded text-white ${colorMap[type]}`}>
      状态
    </span>
  );
}

五、总结

从 CSS Modules 迁移到 UnoCSS 的核心价值在于两个维度：产物尺寸的显著缩减（原子化去重机制）和开发体验的提升（属性化写法、快捷组合）。迁移过程的关键是采用渐进式策略------先共存、再逐步替换，永远不要让迁移阻断现有功能的交付。

需要特别警惕的是动态类名拼接和全局样式丢失这两个问题。前者可以通过 safelist 配置或完整类名映射解决，后者需要利用 preflights 重新声明全局样式。迁移的最终目标不是简单地用一套工具替换另一套工具，而是通过原子化策略让样式代码的体积和维护成本双双收敛到合理区间。