UnoCSS默认按需生成样式，但需确保正确引入uno.css、显式配置presetUno、扩大扫描范围并合理设置插件顺序；否则会出现样式不生效、体积过大或热更新失效等问题。
UnoCSS 默认就是按需生成样式，不需要额外开关 —— 它只提取你在模板、JSX、Vue SFC 中实际用到的类名，生成对应 CSS。但很多人配置后发现 CSS 体积还是大，或热更新失效，问题通常出在扫描路径、预设覆盖或入口引入方式上。
UnoCSS 没生效？先检查 uno.css 是否被正确引入
这是最常踩的坑：Vite 插件已注册，但没在入口文件里 import uno.css，结果页面完全没样式。
- 必须在主入口（如
main.ts或main.js）顶部加一行：import 'uno.css' - 不能写成
import './uno.css'（这是本地文件，不是 UnoCSS 的虚拟模块） - 也不要用
import 'virtual:uno.css'—— 这是旧版写法，2025 年后官方统一为uno.css - 如果用了 SSR 或多入口，每个需要样式的入口都要单独 import
扫描范围太窄，导致部分类名漏生成
UnoCSS 默认只扫描 .ts、.js、.vue、.jsx、.tsx 文件，但如果你的类名写在 Markdown、JSON 配置、甚至字符串拼接里，它就看不见。
- 在
uno.config.ts中显式扩大content范围： content: { files: ['src/**/*.{html,md,vue,ts,js}', 'index.html'] }- 避免用
**扫整个项目（比如node_modules），会拖慢启动速度 - 若类名来自运行时拼接（如
class="text-${color}-500"），得用dynamic规则或提前声明theme.colors，否则无法推导
预设冲突或未启用 presetUno，导致基础类缺失
presetUno() 是 UnoCSS 的核心预设，提供 flex、bg-red-500、px-4 等全部原子类。但它不是默认自动加载的 —— 必须显式写进 presets 数组。
立即学习“前端免费学习笔记（深入）”；
- 错误写法：
presets: [presetIcons(), presetAttributify()]→ 缺少presetUno()，所有基础工具类都不生效 - 正确写法：
presets: [presetUno(), presetAttributify(), presetIcons()] - 如果只想要极简功能（比如仅图标 + 属性模式），仍需保留
presetUno()，否则连text-center都不会生成 -
@unocss/reset是可选重置，不加也不会影响按需生成逻辑，但建议加上避免浏览器默认样式干扰
开发时样式不热更新？可能是 Vite 插件顺序或缓存问题
Vite 插件顺序会影响 UnoCSS 对代码的解析时机。尤其当你同时用了 @vitejs/plugin-vue、vite-plugin-pages 等插件时，UnoCSS 必须在它们之后运行，才能看到编译后的模板内容。
- 确保
UnoCSS()放在vue()之后：plugins: [vue(), UnoCSS()] - 首次运行后，删掉
node_modules/.vite和unocss/缓存目录再重启，避免旧扫描结果残留 - 如果用了
transformerDirectives（支持@apply），它依赖css阶段处理，务必确认它已启用且没被其他 CSS 插件拦截
真正决定“按需”的不是配置开关，而是你写的类名是否能被 UnoCSS 在构建前静态分析到 —— 所以动态 class、服务端渲染的字符串、或写在注释里的类，都不会触发生成。这点和 Tailwind 不同，但正是它轻量的关键所在。
