Vue3 + Vite 项目中引入并配置 UnoCSS 的完整指南

Vue3 + Vite 项目中引入并配置 UnoCSS 的完整指南

在 Vue3 项目中，使用 Vite 作为构建工具时，引入 UnoCSS 作为原子化 CSS 框架可以显著提升开发效率。UnoCSS 以其轻量、灵活和高度可定制的特性，成为 TailwindCSS 的有力替代方案。本文将详细介绍从安装到配置的完整流程，并提供最佳实践和常见问题解决方案。

一、安装依赖

1. 基础安装

在项目根目录下执行以下命令安装核心依赖：

npm install -D unocss
# 或使用 yarn/pnpm
yarn add -D unocss
pnpm add -D unocss

2. 可选预设安装（按需选择）

UnoCSS 的核心功能已内置 preset-uno（包含 Tailwind 兼容工具类），但可根据需求扩展以下预设：

• 属性化模式：支持类似 Tailwind 的 class="text-red-500" 语法

  npm install -D @unocss/preset-attributify
  

• 图标支持：集成超过 10 万个图标库

  npm install -D @unocss/preset-icons
  

• 排版预设：提供专业的排版工具类

  npm install -D @unocss/preset-typography
  

二、配置流程

1. 创建 UnoCSS 配置文件

在项目根目录新建 uno.config.ts（或 unocss.config.ts），示例配置如下：

import { defineConfig, presetAttributify, presetIcons, presetTypography, presetUno } from 'unocss'

export default defineConfig({
  presets: [
    presetUno(), // 默认预设（必须）
    presetAttributify({
      prefix: 'uno:', // 自定义属性前缀（可选）
      ignored: [], // 忽略的属性列表
    }),
    presetIcons({
      scale: 1.2, // 图标缩放比例
      warn: true, // 未找到图标时警告
    }),
    presetTypography(),
  ],
  rules: [
    // 自定义规则（示例：添加圆角变体）
    [/^r-(\d+)$/, ([, d]) => ({ 'border-radius': `${d}px` })],
  ],
  shortcuts: {
    // 快捷类名组合
    'flex-center': 'flex justify-center items-center',
    'btn-primary': 'px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600',
  },
  theme: {
    // 覆盖默认主题
    colors: {
      primary: {
        DEFAULT: '#3B82F6',
        dark: '#2563EB',
      },
    },
  },
})

2. 配置 Vite 插件

修改 vite.config.ts，添加 UnoCSS 插件：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import Unocss from 'unocss/vite'
import { configFile } from './uno.config' // 如果需要手动指定配置路径

export default defineConfig({
  plugins: [
    vue(),
    Unocss({
      configFile: './uno.config.ts', // 可选：显式指定配置文件路径
      // 其他选项...
    }),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

3. 入口文件引入

在 main.ts 或 main.js 中添加以下代码：

import 'uno.css' // 自动生成的 CSS 文件
import { createApp } from 'vue'
import App from './App.vue'

createApp(App).mount('#app')

三、开发环境优化

1. VS Code 插件配置

安装官方插件 UnoCSS 以获得智能提示和实时预览：

1. 搜索并安装 “UnoCSS” 扩展
2. 在项目根目录创建 .vscode/settings.json：

{
  "unocss.enable": true,
  "unocss.root": "./", // 项目根目录
  "unocss.include": ["**/*.{vue,html,jsx,tsx}"] // 监控的文件类型
}

2. 浏览器调试工具

启动开发服务器后，访问 http://localhost:5173/__unocss/ 可查看：

• 生成的 CSS 规则
• 未使用的样式统计
• 性能分析报告

四、进阶配置

1. 自定义规则示例

// uno.config.ts
rules: [
  // 响应式字体大小
  [/^text-(\d+)r?$/, ([, size]) => ({
    'font-size': `${size / 10}rem`,
  })],
  // 状态变体（如 hover/focus）
  [/^hover:(.*)$/, ([, cls]) => ({
    [`&:hover`]: {
      ...extractClass(cls), // 解析嵌套类名
    },
  })],
],

2. 图标库集成

presetIcons({
  collections: {
    // 添加自定义图标库
    myIcons: {
      carbon: {
        'add-alt': '<svg...></svg>', // 直接嵌入 SVG
      },
    },
  },
  // 或通过 npm 包引用
  extraProperties: {
    'display': 'inline-block',
    'vertical-align': 'middle',
  },
})

3. 性能优化

• 按需生成：通过 safelist 和 preflights 控制生成范围

  safelist: ['prose', 'hljs', 'btn-primary'], // 强制保留的类名
  preflights: {
    include: [/\.prose-/], // 只对特定选择器添加基础样式
  },
  

• Tree-shaking：确保构建工具正确处理未使用的样式

五、常见问题解决

1. 样式不生效

• 检查步骤：
  1. 确认 vite.config.ts 中插件顺序正确（UnoCSS 应在 Vue 插件之后）
  2. 检查浏览器开发者工具中的 Sources 面板，确认 uno.css 已加载
  3. 运行 npx unocss inspect 生成样式报告

2. 属性化模式冲突

若同时使用 class 和属性化语法，需确保前缀唯一：

<template>
  <!-- 正确：使用不同前缀 -->
  <div uno:bg-red-500 class="text-blue-500"></div>
</template>

3. TypeScript 类型支持

创建 types/unocss.d.ts 解决类型报错：

declare module 'uno.css' {
  const content: string
  export default content
}

六、生产环境构建

1. 构建优化配置

// vite.config.ts
build: {
  cssCodeSplit: true, // 启用 CSS 代码分割
  minify: 'terser', // 使用 terser 压缩
  rollupOptions: {
    output: {
      manualChunks: {
        vendor: ['vue', '@vueuse/core'],
        styles: ['uno.css'], // 单独打包样式
      },
    },
  },
},

2. 性能监控

通过以下命令分析构建产物：

npx vite build --profile --mode production
# 生成分析报告
npx vite-bundle-visualizer

七、完整示例项目结构

my-vue-project/
├── src/
│   ├── App.vue
│   └── main.ts
├── uno.config.ts
├── vite.config.ts
├── .vscode/
│   └── settings.json
└── package.json

八、版本兼容性说明

九、替代方案对比

十、总结

通过本文的详细配置，您已掌握：

1. UnoCSS 的核心安装与预设扩展
2. Vite 插件的深度集成
3. 开发工具链的优化配置
4. 常见问题的系统化解决方案

建议定期检查 UnoCSS 官方文档 获取最新特性更新。对于大型项目，可考虑结合 unplugin-auto-import 实现自动导入，进一步提升开发效率。