uni-app 中配置 UnoCSS

本文档记录在 uni-app 项目中集成 UnoCSS 原子化 CSS 引擎的完整过程。

1. 安装依赖

pnpm add -D unocss @uni-helper/unocss-preset-uni

核心依赖说明：

• unocss: UnoCSS 核心包
• @uni-helper/unocss-preset-uni: 专为 uni-app 优化的预设，自动转换 rpx 单位，兼容小程序/App 平台

2. 配置 Vite 插件

在 vite.config.ts 中引入 UnoCSS 插件：

import { defineConfig } from 'vite';
import uni from '@dcloudio/vite-plugin-uni';

export default defineConfig(async () => {
  const UnoCSS = (await import('unocss/vite')).default; // 动态导入 UnoCSS 插件，兼容 HBuilderX
  return {
    plugins: [
      uni.default(),
      UnoCSS() // 添加 UnoCSS 插件
      // 其他插件...
    ]
  };
});

3. 创建 UnoCSS 配置文件

在项目根目录创建 uno.config.ts：

import { presetUni } from '@uni-helper/unocss-preset-uni';
import { defineConfig, presetIcons, transformerDirectives, transformerVariantGroup } from 'unocss';

export default defineConfig({
  presets: [
    presetUni(), // uni-app 预设，必需
    presetIcons({
      scale: 1.2,
      warn: true,
      extraProperties: {
        display: 'inline-block',
        'vertical-align': 'middle'
      }
    })
  ],
  transformers: [
    transformerDirectives(), // 支持 @apply 等指令
    transformerVariantGroup() // 支持变体组简写，如 hover:(bg-gray-400 font-medium)
  ]
});

配置说明：

• presetUni(): 自动处理 rpx/px 单位转换，支持小程序/App 平台特性
• presetIcons(): 可选，支持图标集（需额外安装 @iconify-json/* 包）
• transformerDirectives(): 支持 Tailwind 风格的 @apply 指令
• transformerVariantGroup(): 简化变体书写，如 hover:(text-red bg-blue)

4. 引入 UnoCSS 样式

方式一：在 main.ts 中引入（推荐 CLI 编译）

import { createSSRApp } from 'vue';
import App from './App.vue';
import 'uno.css'; // 引入 UnoCSS 生成的样式

export function createApp() {
  const app = createSSRApp(App);
  return { app };
}

平台差异说明：

• H5: 方式一
• 小程序 : 推荐方式一（main.ts 引入）
• App（Android/iOS） :
  • CLI 编译：方式一
  • HBuilderX 编译：方式二，将样式放在 App.vue 中以确保注入到 view 层

5. 使用 UnoCSS

配置完成后即可在模板中使用工具类：

<template>
  <view class="flex justify-center items-center h-screen">
    <view class="bg-blue-500 text-white p-4 rounded-lg"> Hello UnoCSS in uni-app! </view>
  </view>
</template>

6. 常见问题

6.1 样式在 App 端不生效

原因： uni-app 的 App 端分为 service 层和 view 层，main.ts 的引入只在 service 层生效。

解决方案：

1. 将 import 'uno.css' 移至 App.vue 的 <style> 块
2. 或使用内联样式/自定义组件包裹

6.2 HBuilderX 编译报错 "Cannot find module 'uno.css'"

原因： HBuilderX 不支持 virtual:uno.css 虚拟模块。

解决方案：

// 使用普通导入，不要使用 virtual: 前缀
import 'uno.css';

6.3 单位不是 rpx

原因： 未使用 presetUni() 预设。

解决方案： 确保 uno.config.ts 中包含：

presets: [presetUni()];

6.4 动态类名不生效

原因： UnoCSS 静态扫描无法识别动态拼接的类名。

错误示例：

<view :class="`text-${color}-500`"></view>

正确做法：

<view :class="color === 'red' ? 'text-red-500' : 'text-blue-500'"></view>

或使用 safelist 配置：

// uno.config.ts
export default defineConfig({
  safelist: ['text-red-500', 'text-blue-500']
  // ...
});

7. 开发体验优化

7.1 VSCode 插件

安装 UnoCSS 插件获得：

• 类名自动补全
• 类名悬停预览
• 类名颜色高亮

7.2 UnoCSS Inspector

开发模式下访问 http://localhost:5173/__unocss 查看：

• 当前生成的所有样式
• 使用的工具类统计
• 样式文件大小

7.3 配置别名

在 uno.config.ts 中自定义简写：

export default defineConfig({
  shortcuts: {
    btn: 'px-4 py-2 rounded bg-blue-500 text-white hover:bg-blue-600',
    card: 'bg-white rounded-lg shadow p-4'
  }
});

使用：

<view class="btn">按钮</view>
<view class="card">卡片</view>

8. 性能优势

相比传统 CSS 方案，UnoCSS 在 uni-app 中的优势：

1. 按需生成：只生成使用到的样式，最终包体积更小
2. 零运行时：编译时生成，无运行时开销
3. 统一规范：团队成员使用相同工具类，样式一致性更好
4. 跨平台兼容：自动处理不同平台的单位差异（rpx/px）

9. 参考资源

• UnoCSS 官方文档
• uni-helper UnoCSS 预设
• UnoCSS Interactive Docs