UnoCSS不能直接优化纯HTML文件，因其不解析HTML，仅扫描源码中class字符串生成CSS；必须通过构建工具（如Vite）显式配置扫描HTML路径或使用CLI指定--files参数。
纯 HTML 文件无法直接“配置” UnoCSS——它不解析 HTML，只扫描源码中出现的 class 字符串并生成对应 CSS 规则。你看到的 class 生效与否，取决于构建流程是否把 HTML 文件纳入扫描范围。
UnoCSS 为什么对裸 HTML 文件没反应
常见错误现象：bg-red-500 写在 index.html 里，页面完全没变色；开发者反复检查 uno.config.ts，却漏掉了最关键的一环：UnoCSS 根本没读到这个文件。
原因很直接：UnoCSS 是一个构建时工具，不是运行时样式引擎。它不会像浏览器那样解析 HTML DOM，也不会监听文件变化后自动重扫静态 HTML。它依赖 Vite 插件（如 vite-plugin-unocss）或 CLI 工具显式声明要扫描的路径。
-
vite-plugin-unocss默认只扫描**/*.ts、**/*.vue、**/*.jsx等源码文件，不包含**/*.html，除非你手动加进去 - 如果你用
@unocss/cli，必须显式传参：unocss --files "src/**/*.html"，否则它压根不看 HTML - 直接双击打开
index.html（无服务器、无构建），UnoCSS 完全不参与，virtual:uno.css也不会被注入
vite.config.ts 中必须显式启用 HTML 扫描
Vite 项目里，仅引入 UnoCSS() 插件还不够。默认配置下，插件会跳过 HTML 文件——这是多数人踩坑的起点。
你需要在 vite.config.ts 的插件配置中，为 UnoCSS() 显式开启 HTML 支持：
import UnoCSS from 'unocss/vite'
export default defineConfig({
plugins: [
UnoCSS({
// 必须加这一项，否则 HTML 不被扫描
include: [
'**/*.html',
'**/*.ts',
'**/*.tsx',
'**/*.vue',
],
}),
],
})
-
include是数组，顺序无关，但必须包含'**/*.html' - 如果项目有多个 HTML 入口（如
popup.html、options.html），确保路径匹配上 - 改完配置后需重启 Vite 开发服务器，热更新不触发重新扫描 HTML
HTML 中 class 写法和常见失效点
UnoCSS 对 class 名称本身没有特殊限制，但部分写法在 HTML 环境中容易出错，尤其涉及空格、引号、属性化模式时。
- 不要在 class 属性里混用单双引号：—— HTML 只认第一个
class，后面被忽略- 属性化模式（如
text="red-500"）需要presetAttributify()启用，且只在 Vue/Svelte 等支持自定义属性的框架中生效；纯 HTML 不支持- 图片居中别写
text-center要加在父容器上，或配合block mx-auto（且图片必须是块级）- 图标类如
i-mdi-home需提前安装对应图标包（如@iconify-json/mdi），否则生成的 CSS 里没有该规则如何验证 HTML 是否真被 UnoCSS 处理了
最可靠的验证方式不是看页面效果，而是检查生成结果：
- 启动开发服务器后，打开浏览器开发者工具 → Elements 面板，查看
中是否注入了标签，内容含.bg-red-500{background-color:#ef4444}这类规则 - 或者检查网络面板，确认请求了
/@unocss/css或类似路径（Vite 插件注入的虚拟 CSS） - 更底层：运行
npx unocss --watch并指定 HTML 路径，看终端输出是否列出你写的 class —— 如果没列，说明扫描失败
真正容易被忽略的是：UnoCSS 的“按需”是基于构建时的静态扫描，不是运行时的动态匹配。哪怕你在 HTML 里写了
class="hover:bg-blue-500"，若没配hover:变体支持（比如没开presetUno()或没在配置里声明variants），这个 hover 效果也不会生成。 - 属性化模式（如
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
