如何在Vite里集成UnoCSS并启用预设指令_借助CSS快捷方式大幅提升编码速度

UnoCSS插件必须在vite.config.ts的plugins数组中显式调用UnoCSS()，否则原子类不生效；@apply需通过transformerDirectives启用；shortcuts须定义在uno.config.ts的shortcuts字段；且必须import 'virtual:uno.css'。

UnoCSS插件必须在vite.config.ts中显式启用

不加UnoCSS()插件，哪怕装了包、写了配置，class里写的原子类也不会生效。Vite默认不识别virtual:uno.css，也不扫描模板中的工具类。

常见错误现象：class="text-red-500 p-4"完全没样式，浏览器开发者工具里查不到对应 CSS 规则。

正确做法是确保vite.config.ts的plugins数组中包含：

import UnoCSS from 'unocss/vite'// ...plugins: [  vue(),  UnoCSS(), // 必须调用，不能只 import]

如果你把配置抽到uno.config.ts，记得传入configFile参数：

立即学习“前端免费学习笔记（深入）”；

UnoCSS({  configFile: './uno.config.ts'})

@apply指令依赖transformerDirectives

@apply不是默认开启的。它属于 UnoCSS 的 transformer 功能，需要手动引入并注册，否则.btn { @apply px-4 py-2 bg-blue-500; }会直接报错或被忽略。

你得在uno.config.ts里明确启用：

• 导入transformerDirectives（来自unocss）
• 把它加进transformers数组

示例配置片段：

import { defineConfig, presetUno, transformerDirectives } from 'unocss'export default defineConfig({  presets: [presetUno()],  transformers: [transformerDirectives()] // 关键一行})

注意：仅在css文件或<style>块中可用，<template>里不能写@apply。

快捷方式shortcuts要写在uno.config.ts顶层

快捷类名（如btn-primary）不会自动从main.css或index.css里提取——它们必须定义在 UnoCSS 配置对象的shortcuts字段下，否则编译时不会生成对应规则。

容易踩的坑：

• 把shortcuts写在rules里，或嵌套在theme中 → 无效
• 用shortcuts: { 'btn': 'px-3 py-1 rounded' }没问题，但若想支持动态命名（如btn-red），得用正则数组写法：[/^btn-(.*)$/, ([_, c]) => `bg-${c}-500 text-white`]
• 快捷方式里的类名必须是 UnoCSS 已知的原子类（比如px-3要能被presetUno解析），否则最终 CSS 会缺失

一个实用组合：

shortcuts: [  {    'flex-center': 'flex justify-center items-center',    'btn-sm': 'px-2 py-1 text-xs rounded',  },  [/^btn-(w+)$/, ([_, color]) => `px-3 py-1.5 rounded bg-${color}-500 text-white`]]

virtual:uno.css必须在入口JS中import

UnoCSS 不会自动注入样式。你必须在main.ts（或main.js）最顶部显式引入虚拟 CSS 文件：

import 'virtual:uno.css'

不是uno.css，也不是@unocss/reset.css——只有virtual:uno.css才是运行时生成的完整原子类集合。

如果项目用了暗黑模式或自定义 reset，可以额外加一行：

import '@unocss/reset/tailwind.css'

但顺序很重要：reset要在virtual:uno.css之前，否则重置样式可能被覆盖。

uni-app 或 WebExt 等特殊环境略有差异（比如 uni-app 推荐import 'uno.css'），但标准 Vite + Vue3 项目请严格用virtual:uno.css。

最常被忽略的是：改完uno.config.ts后没重启开发服务器，导致新定义的shortcuts或rules不生效——这跟热更新机制有关，不是 bug，是设计使然。