UnoCSS

UnoCSS

UnoCSS 是一款即时按需原子 CSS 引擎。它只生成你实际使用的工具类对应的 CSS——无需解析、无需 AST、无需扫描。速度比 Tailwind CSS JIT 快 5 倍，压缩后约为 6kb（min+brotli），且零依赖。

何时使用此技能

在以下情况使用此技能……	在以下情况使用其他工具……
配置工具优先的 CSS	转译/压缩 CSS（使用 Lightning CSS）
配置 UnoCSS 预设和规则	检查 CSS 规则（使用 Stylelint）
与 Vite/Nuxt/Astro 集成	需要 Tailwind 专属插件生态系统
根据类名生成原子 CSS	编写传统 CSS 架构（BEM 等）
使用预设提供的纯 CSS 图标	需要 CSS-in-JS 运行时（使用 styled-components 等）
用更快的替代方案替换 Tailwind CSS

核心专长

• 即时生成：无需解析或 AST——直接通过正则表达式提取类名
• 预设驱动：所有工具类均来自预设，且完全可自定义
• 框架无关：支持 Vite、Webpack、PostCSS、Nuxt、Astro、Svelte、CLI
• 可扩展：自定义规则、变体、快捷方式、提取器、转换器
• 检查器：内置开发工具，可调试生成的工具类

安装

# Vite project (most common)
npm add -D unocss

# Bun
bun add -d unocss

# Standalone CLI
npm add -D @unocss/cli

Vite 集成

基本设置

// vite.config.ts
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [UnoCSS()]
})

// main.ts - import the virtual stylesheet
import 'virtual:uno.css'

配置文件

// uno.config.ts
import { defineConfig, presetWind3 } from 'unocss'

export default defineConfig({
  presets: [presetWind3()]
})

与 Lightning CSS 搭配（推荐组合）

// vite.config.ts
import UnoCSS from 'unocss/vite'
import browserslist from 'browserslist'
import { browserslistToTargets } from 'lightningcss'

export default defineConfig({
  plugins: [UnoCSS()],
  css: {
    transformer: 'lightningcss',
    lightningcss: {
      targets: browserslistToTargets(browserslist('>= 0.25%'))
    }
  },
  build: {
    cssMinify: 'lightningcss'
  }
})

插件模式

模式	使用场景	设置
全局（默认）	标准应用	在入口文件中使用 import 'virtual:uno.css'
Vue 作用域	Vue 组件隔离	注入到 <style scoped> 块中
Shadow DOM	Web Components	在组件样式中添加 @unocss-placeholder
按模块（实验性）	模块作用域 CSS	每个模块使用单独的 CSS 样式表
按构建块（实验性）	多页面应用	每个代码块使用单独的 CSS 样式表

框架专属插件顺序

框架	UnoCSS 插件位置
React（Babel）	位于 @vitejs/plugin-react 之前
Svelte/SvelteKit	位于 Svelte 插件之前
Vue	任意位置（默认配置即可运行）
Solid/Preact	查看文档了解顺序

CLI 用法

# Generate CSS from source files
unocss "src/**/*.{html,tsx,vue}" -o dist/uno.css

# Multiple glob patterns
unocss "src/**/*.tsx" "pages/**/*.vue" -o dist/uno.css

# Minified output
unocss "src/**/*.tsx" -o dist/uno.css --minify

# Output to stdout (pipe-friendly)
unocss "src/**/*.tsx" --stdout

# Watch mode for development
unocss "src/**/*.tsx" -o dist/uno.css --watch

# With specific config file
unocss "src/**/*.tsx" -o dist/uno.css --config uno.config.ts

# Include preflight styles
unocss "src/**/*.tsx" -o dist/uno.css --preflights

# Use specific preset without config
unocss "src/**/*.tsx" -o dist/uno.css --preset wind4

配置

预设

// uno.config.ts
import {
  defineConfig,
  presetWind3,        // Tailwind CSS v3 compatible utilities
  presetIcons,        // Pure CSS icons from Iconify
  presetAttributify,  // Attributify mode (utilities as HTML attributes)
  presetTypography,   // Typography prose classes
  presetWebFonts,     // Web font loading
  presetMini,         // Minimal preset (subset of wind)
} from 'unocss'

export default defineConfig({
  presets: [
    presetWind3(),
    presetIcons({
      scale: 1.2,
      cdn: 'https://esm.sh/'
    }),
    presetAttributify(),
    presetTypography(),
    presetWebFonts({
      provider: 'google',
      fonts: { sans: 'Inter', mono: 'Fira Code' }
    })
  ]
})

Wind3 与 Wind4

预设	兼容性	说明
presetWind3()	Tailwind CSS v3	稳定、应用广泛
presetWind4()	Tailwind CSS v4	较新，采用 CSS 优先配置

自定义规则

// uno.config.ts
export default defineConfig({
  rules: [
    // Static rule
    ['custom-padding', { padding: '1rem' }],
    // Dynamic rule
    [/^m-(\d+)$/, ([, d]) => ({ margin: `${Number(d) / 4}rem` })],
  ]
})

快捷方式

// uno.config.ts
export default defineConfig({
  shortcuts: {
    'btn': 'py-2 px-4 font-semibold rounded-lg shadow-md',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-700',
    'card': 'p-4 rounded-lg shadow bg-white dark:bg-gray-800',
  }
})

主题

// uno.config.ts
export default defineConfig({
  theme: {
    colors: {
      primary: '#3b82f6',
      secondary: '#64748b',
    },
    breakpoints: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
    }
  }
})

安全列表

// uno.config.ts — pre-generate classes not found in source scanning
export default defineConfig({
  safelist: [
    'bg-red-500',
    'text-white',
    ...Array.from({ length: 5 }, (_, i) => `p-${i + 1}`)
  ]
})

图层

// uno.config.ts — control CSS specificity ordering
export default defineConfig({
  layers: {
    components: -1,  // Before utilities
    default: 1,      // Utilities
    utilities: 2,    // Higher specificity utilities
  }
})

图标预设

使用任意 Iconify 图标集中的纯 CSS 图标：

# Install icon collections
npm add -D @iconify-json/mdi @iconify-json/lucide

// uno.config.ts
import { presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetIcons({
      extraProperties: {
        'display': 'inline-block',
        'vertical-align': 'middle',
      }
    })
  ]
})

<div class="i-mdi-home text-2xl" />
<div class="i-lucide-settings w-6 h-6" />

检查器

内置检查器可在开发期间显示生成的 CSS：

// main.ts
import 'virtual:uno.css'

在开发服务中访问 /__unocss，即可查看检查器中的以下内容：

• 生成的 CSS 规则
• 每个文件匹配到的类名
• 配置概览

DevTools 集成

// main.ts — enable class editing in browser DevTools
import 'virtual:uno.css'
import 'virtual:unocss-devtools'

变体组

常用前缀的简写形式：

<div class="hover:bg-blue-500 hover:text-white hover:font-bold" />


<div class="hover:(bg-blue-500 text-white font-bold)" />

使用转换器启用：

import { transformerVariantGroup } from 'unocss'

export default defineConfig({
  transformers: [transformerVariantGroup()]
})

面向 Agent 的优化

场景	命令
快速生成	unocss "src/**/*.tsx" -o uno.css --minify
输出到标准输出（管道）	unocss "src/**/*.tsx" --stdout
监视模式	unocss "src/**/*.tsx" -o uno.css -w
检查配置	查看 uno.config.ts 中的预设和规则
检查导入	在入口文件中搜索 virtual:uno.css
检查工具类	在开发服务中访问 /__unocss

快速参考

标志	别名	说明
--out-file <file>	-o	输出文件名（默认：uno.css）
--stdout		将 CSS 写入标准输出
--watch	-w	监视文件更改
--minify	-m	压缩生成的 CSS
--config <file>	-c	配置文件路径
--preflights		包含预检/重置样式
--preset <name>		使用 wind3 或 wind4 预设
--debug		启用调试模式

References

• Official docs: https://unocss.dev
• Interactive playground: https://unocss.dev/play
• Vite integration: https://unocss.dev/integrations/vite
• CLI reference: https://unocss.dev/integrations/cli
• Presets: https://unocss.dev/presets