UnoCSS

即时按需的原子化 CSS 引擎，高性能、灵活可扩展的 CSS 原子类生成方案。

技术简介说明

UnoCSS 是由 Anthony Fu（尤雨溪的 Vue 核心团队成员）于 2021 年创建的即时按需原子化 CSS 引擎。它的设计哲学是将原子化 CSS 抽象为一个通用引擎层，通过预设（preset）系统支持 Tailwind CSS、Windi CSS 等多种语法，同时提供极高的可扩展性。UnoCSS 不绑定任何特定的工具类约定，开发者可以自由定义自己的原子类规则。

UnoCSS 的核心优势在于性能——它不依赖 AST 解析、不做源码扫描，而是通过正则匹配即时生成所需的 CSS，这使得它的开发体验极为流畅。在 Anthony Fu 的生态体系中（Vue、Vite、Nuxt、Vitest、Slidev 等），UnoCSS 是默认的样式方案。

截至 2026 年，UnoCSS 已发展到 v66.x 版本，持续保持活跃开发。新增的 @unocss/preset-wind4 预设提供了对 Tailwind CSS v4 语法的兼容支持，使其成为同时兼容多代 Tailwind 语法的唯一原子化 CSS 引擎。

基本信息

• 官网：https://unocss.dev
• GitHub：https://github.com/unocss/unocss
• License：MIT
• 最新版本：v66.7.4（2026 年 6 月）
• 主要维护者/公司：Anthony Fu（@antfu）
• GitHub Stars：18.9k+
• 包体积：~6KB（min+brotli），零依赖

快速上手

安装

Vite 项目（推荐）

# npm
npm install -D unocss
 
# pnpm
pnpm add -D unocss

// vite.config.ts
import UnoCSS from 'unocss/vite'
 
export default {
  plugins: [
    UnoCSS(),
  ],
}

// uno.config.ts
import { defineConfig, presetUno, presetAttributify, presetIcons } from 'unocss'
 
export default defineConfig({
  presets: [
    presetUno(),        // 默认预设，兼容 Tailwind/Windi 语法
    presetAttributify(), // 属性化模式
    presetIcons(),       // 图标支持
  ],
})

// main.ts - 入口文件导入生成的 CSS
import 'uno.css'

Nuxt 项目

pnpm add -D @unocss/nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@unocss/nuxt'],
})

PostCSS 项目

pnpm add -D @unocss/postcss

// postcss.config.js
module.exports = {
  plugins: {
    '@unocss/postcss': {},
  },
}

基础配置

// uno.config.ts
import {
  defineConfig,
  presetUno,
  presetAttributify,
  presetWind4,
  presetIcons,
  transformerDirectives,
  transformerVariantGroup,
} from 'unocss'
 
export default defineConfig({
  presets: [
    presetWind4(),       // Tailwind CSS v4 兼容预设
    presetAttributify(), // 属性化模式
    presetIcons({        // 图标预设
      scale: 1.2,
      cdn: 'https://esm.sh/',
    }),
  ],
  theme: {
    colors: {
      brand: {
        primary: 'var(--color-brand-primary)',
      },
    },
  },
  shortcuts: {
    // 快捷方式：组合多个工具类
    'btn': 'px-4 py-2 rounded-lg font-medium inline-flex items-center justify-center',
    'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
  },
  transformers: [
    transformerDirectives(),    // 支持 @apply 等指令
    transformerVariantGroup(),  // 支持 hover:(bg-red text-white) 语法
  ],
})

最小示例

<!-- 标准工具类模式 -->
<div class="text-center p-8">
  <h1 class="text-3xl font-bold text-gray-900 dark:text-white">
    Hello UnoCSS
  </h1>
  <p class="mt-4 text-gray-500">即时按需原子化 CSS</p>
  <button class="mt-6 btn-primary">开始使用</button>
</div>
 
<!-- 属性化模式 -->
<div text-center p-8>
  <h1 text="3xl" font="bold" text="gray-900 dark:white">
    属性化模式
  </h1>
  <button bg="blue-500 hover:blue-600" text="white" px-4 py-2 rounded-lg>
    点击我
  </button>
</div>
 
<!-- 图标支持 -->
<div class="i-carbon-logo-github text-2xl" />

核心概念与架构

引擎架构

UnoCSS 采用分层架构设计：

┌─────────────────────────────────┐
│     框架集成层（Vite/Nuxt/...）   │
├─────────────────────────────────┤
│     Transformer 层              │
│  (Directives/VariantGroup/...)  │
├─────────────────────────────────┤
│     Preset 层（预设）             │
│  (Uno/Wind3/Wind4/Attributify) │
├─────────────────────────────────┤
│     核心引擎层（@unocss/core）    │
│  规则匹配 → 即时生成 CSS         │
├─────────────────────────────────┤
│     运行时 / 构建时输出           │
└─────────────────────────────────┘

核心工作原理

1. 正则匹配：UnoCSS 使用正则表达式而非 AST 解析来识别工具类，这使得它极为快速
2. 即时生成：发现匹配的工具类后即时生成对应的 CSS，无需预构建
3. 预设系统：预设定义了一组规则（rules）、变体（variants）和主题（theme），可以灵活组合
4. 零依赖：核心引擎无任何外部依赖，可在浏览器中运行

预设（Preset）系统

预设是 UnoCSS 的核心抽象：

核心特性

• 即时按需引擎：不扫描源码，按需生成，开发体验极为流畅
• 预设系统：通过预设支持 Tailwind v3/v4、Windi CSS 等多种语法
• 属性化模式：<div text="center" font="bold"> 更简洁的 HTML 写法
• 纯 CSS 图标：通过 presetIcons 使用任何图标集作为 CSS 类
• 快捷方式（Shortcuts）：将多个工具类组合为一个自定义类
• Variant Group：hover:(bg-red text-white) 简化变体书写
• @apply 指令：在 CSS 中使用工具类组合
• 运行时 CDN 模式：直接在浏览器中运行，动态检测 DOM 变化
• 零依赖：核心包无任何外部依赖，体积极小（~6KB）
• 热更新（HMR）：修改配置或 HTML 后即时更新样式

生态图

官方集成

社区预设

关键依赖

• @unocss/core：核心引擎
• magic-string：字符串转换
• css-tree：CSS 解析（仅在 transformer 中使用）

适用场景

• Vue / Nuxt 生态项目（与 Vite/Nuxt 深度集成，是一等公民样式方案）
• 需要兼容多代 Tailwind 语法的项目（Wind3 + Wind4 预设同时支持 v3 和 v4 语法）
• 需要极致开发体验的项目（即时编译、零扫描、微秒级构建）
• 纯 CSS 图标方案（通过 presetIcons 使用任何图标集，无需 SVG 导入）
• 跨框架组件库（预设系统使样式方案可复用）
• 浏览器内运行时（通过 CDN 运行时在浏览器中动态生成样式）
• 已有项目渐进式引入（PostCSS 插件模式支持渐进迁移）

开发与工程化

开发流程

# 开发模式（Vite 集成自动 HMR）
pnpm dev
 
# 生产构建
pnpm build
 
# CLI 模式（独立构建）
pnpm unocss "src/**/*.html" -o dist/uno.css

属性化模式使用

<!-- 属性化模式：HTML 更简洁 -->
<button
  bg="blue-500 hover:blue-600"
  text="white sm"
  px="4"
  py="2"
  rounded="lg"
  font="medium"
>
  属性化按钮
</button>
 
<!-- 等效的标准写法 -->
<button class="bg-blue-500 hover:bg-blue-600 text-white text-sm px-4 py-2 rounded-lg font-medium">
  标准按钮
</button>

图标系统

<!-- 使用任意图标集 -->
<div class="i-mdi-home text-2xl text-blue-500" />
<div class="i-carbon-checkmark text-green-500" />
<div class="i-ph-heart-fill text-red-500" />

CI/CD 集成

# GitHub Actions
- name: Build with UnoCSS
  run: |
    pnpm install
    pnpm build

性能与安全

性能特点

• 构建速度：比 Tailwind CSS / Windi CSS 快约 5 倍（无 AST 解析开销）
• 增量构建：微秒级响应文件变化
• 输出体积：仅包含实际使用的样式，与 Tailwind 相当
• 运行时：CDN 运行时包约 6KB（min+brotli）

优化建议

• 优先使用 presetWind4 获取最新的 CSS 特性支持
• 合理使用 shortcuts 减少重复类组合
• 图标预设建议使用 CDN 模式避免包体积膨胀
• 生产环境启用 CSS 压缩

安全注意事项

• CDN 运行时模式不建议在生产环境大规模使用（有运行时解析开销）
• 自定义规则（rules）中避免使用 eval 或不受信任的输入
• presetIcons CDN 模式需要配置 CSP 头

性能基准

技术对比

最佳实践

生产环境建议

1. 选择正确的预设：新项目推荐使用 presetWind4（Tailwind v4 兼容）
2. 利用 shortcuts：将重复的类组合提取为 shortcuts，提高可维护性
3. 图标优化：使用 presetIcons 的 customCollections 避免 CDN 依赖
4. TypeScript 类型安全：为 uno.config.ts 添加类型注解

// uno.config.ts
import type { UserConfig } from 'unocss'
 
export default defineConfig({
  // ...
}) satisfies UserConfig

常见陷阱

• 预设冲突：不要同时使用 presetUno 和 presetWind3/4，它们有规则重叠
• 属性化模式与框架冲突：某些框架（如 Vue）的属性绑定可能冲突
• Transformer 顺序：transformerDirectives 必须在 presets 之后加载
• CSS 变量主题：Wind4 预设使用 CSS 变量，需要确保 reset 样式正确

推荐模式

// 推荐的预设组合
export default defineConfig({
  presets: [
    presetWind4(),
    presetAttributify(),
    presetIcons({
      scale: 1.2,
      warn: true,
    }),
  ],
  transformers: [
    transformerDirectives(),
    transformerVariantGroup(),
  ],
  shortcuts: [
    {
      'btn': 'px-4 py-2 rounded-lg font-medium inline-flex items-center gap-2 transition-colors',
      'btn-primary': 'btn bg-blue-500 text-white hover:bg-blue-600',
      'btn-ghost': 'btn bg-transparent hover:bg-gray-100 dark:hover:bg-gray-800',
    },
  ],
})

技术局限与边界

已知限制

• 文档覆盖度：相比 Tailwind CSS，社区教程和学习资源较少
• 生态规模：第三方组件库和模板少于 Tailwind CSS
• 属性化模式：与 JSX/TSX 语法不完全兼容（React 项目需谨慎）
• 部分高级 Tailwind 特性：Tailwind CSS v4 的新特性可能需要等待预设跟进

不适用场景

• 团队全部使用 Tailwind CSS：UnoCSS 的差异化优势在小团队中不明显
• 邮件模板开发：运行时模式不适合邮件客户端
• 极端性能要求：虽然 UnoCSS 已经很快，但 Tailwind CSS v4 的 Rust 引擎也在追赶

迁移注意事项

• 从 Tailwind CSS 迁移：使用 presetWind3 或 presetWind4 实现近乎零成本的语法兼容
• 从 Windi CSS 迁移：UnoCSS 是 Windi CSS 的精神继任者（Anthony Fu 同为贡献者）
• 配置迁移：uno.config.ts 的 preset 系统比 tailwind.config.js 更灵活

学习资源

• 官方文档：https://unocss.dev
• 交互游乐场：https://unocss.dev/play/
• Anthony Fu 博客：https://antfu.me/posts/reimagine-atomic-css
• 视频教程：
  • WTF is UnoCSS?
  • UnoCSS 全介绍
• 社区资源：
  • Discord：https://chat.antfu.me（Anthony Fu 的 Discord 服务器）
  • GitHub Discussions：https://github.com/unocss/unocss/discussions
  • Anthony Fu Twitter/X：https://x.com/antfu7
• 中文资源：
  • UnoCSS 中文文档：https://unocss.nodejs.cn
  • Bilibili 教程：搜索 "UnoCSS"

2026 年现状

最新版本

• 稳定版：v66.7.4（2026 年 6 月）
• 新增 preset-wind4：完整支持 Tailwind CSS v4 语法
• 新增 @unocss/twoslash：代码片段类型高亮集成

发展趋势

• Tailwind v4 兼容：preset-wind4 使 UnoCSS 成为兼容多代 Tailwind 语法的唯一方案
• Anthony Fu 生态整合：与 Vite、Nuxt、Vitest 等核心工具持续深度集成
• Vite DevTools：Anthony Fu 主导的 Vite DevTools 项目将包含 UnoCSS 集成
• 社区预设生态：shadcn、daisyUI、PrimeVue 等社区预设持续增长

社区活跃度

• GitHub Star 18.9k+，在 Vue/Vite 生态中有极高的渗透率
• Anthony Fu 持续维护，版本发布频繁（v66.x 系列持续迭代）
• 社区预设生态活跃，多个第三方预设持续更新

未来路线图

• 持续完善 preset-wind4 对 Tailwind v4 新特性的覆盖
• 增强运行时性能和浏览器兼容性
• 扩展 IDE 支持和类型推断
• 探索与 CSS Houdini 的深度集成