UnoCSS 不能直接优化纯 HTML 文件，因其不解析 HTML，仅扫描源码中 class 字符串生成 CSS；需通过构建工具（如 Vite）或 CLI 显式配置扫描 HTML 路径。
UnoCSS 能不能直接优化纯 HTML 文件
不能。unocss 本身不解析 html，它只扫描源码中的 class 字符串，生成对应 css 规则。如果你只有 index.html，没走构建流程（比如没有 vite、webpack 或 cli 扫描），@unocss/cli 或 unocss 插件根本看不到那些 class——它们只是静态文本。
常见错误现象：bg-red-500 写进 HTML 里，页面没生效，开发者以为是 UnoCSS 没启用，其实是压根没触发扫描。
- 必须通过构建工具或 CLI 主动读取 HTML 文件路径（如
vite-plugin-unocss默认支持**/*.html） - 若用
@unocss/cli，需显式传入--files "src/**/*.html" - Vite 项目中确保
unocss插件在plugins数组里，且 HTML 在public/外（否则不会被插件处理）
HTML 中 class 写法有哪些限制
UnoCSS 对 class 名的识别是“按空格切分 + 逐个匹配”，所以它不关心你写在哪，只关心字符串是否合法。但容易踩坑的是：动态拼接、JS 注入、服务端模板变量会绕过扫描。
使用场景：静态 HTML、PHP 模板、Svelte/Vue 单文件组件的 <template></template> 部分都支持；但 document.body.className = 'text-blue-600' 这种运行时写法不会被提取。
- 避免用 JS 拼接 class：
class="mt-${size} text-${color}"→ UnoCSS 看不到变量值，无法生成对应规则 - 服务端渲染（如 PHP）中，若 class 是 PHP 变量插值（
class="= $cls ?>"），需确保构建时能访问最终 HTML 输出，或改用预定义原子类名 - 支持转义空格和引号，但别写
class="hover:underline focus:outline"这种带冒号空格的——它会被当两个 class：hover:underline和focus:outline，没问题；但class="hover:text-red-500"是单个合法原子 class
为什么 HTML 里用了 class 却没生成对应 CSS
最常见原因是匹配模式未启用或内容未被扫描到。UnoCSS 默认只处理 .ts、.js、.vue、.svelte 等扩展名，HTML 不在默认列表里（Vite 插件除外）。
立即学习“前端免费学习笔记（深入）”；
性能影响：扫描更多文件 = 启动更慢、HMR 延迟略高，但对最终 CSS 体积无额外开销——未用的原子类不会输出。
- Vite 用户检查
vite.config.ts是否有Unocss()，且没配include把**/*.html排除掉 - CLI 用户运行
npx unocss --watch --files "src/**/*.html" --out-file unocss.css，确认路径 glob 匹配到了目标文件 - 检查浏览器 DevTools 的
<style id="unocss"></style>标签是否存在，以及是否包含你用的 class 对应的 CSS 规则 - 如果用了
shortcuts或theme自定义，确保这些配置在uno.config.ts中已导出，并被 CLI / 插件加载
要不要把所有 HTML 放进构建流程
要。哪怕只是几个静态页，也建议用 Vite（或最小化 Rollup）跑一遍，否则 UnoCSS 就是摆设。纯手写 HTML + 手动引入 unocss.css 只能用预设规则，没法按需提取。
兼容性影响：生成的 CSS 是标准 CSS，无浏览器兼容问题；但若用了 dark:、group- 等需要 DOM 结构配合的功能，得确保 HTML 结构满足前提（比如 group 类必须出现在父元素上）。
- 最小可行方案：新建
vite.config.ts，只配Unocss()和build.rollupOptions.input = 'src/index.html'，然后vite build - 别试图用
unocss -c uno.config.ts src/index.html直接转换单文件——它不解析 HTML 标签，只当普通文本扫 class - 如果 HTML 由 CMS 输出或部署后动态生成，UnoCSS 就不适合，应改用预编译全量 CSS 或服务端集成方案
真正卡住人的地方往往不是配置多难，而是默认不处理 HTML —— 很多人试了半小时发现 class 没生效，回头一看 vite.config.ts 里连 Unocss 插件都没加。
