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，是设计使然。
