UnoCSS 类名不完整的核心原因是提取器仅识别源码中静态字面量字符串，无法解析变量拼接、运行时DOM操作、JSX/Vue动态绑定等非静态类名；需通过safelist兜底或补全content.filesystem路径。
UnoCSS 生成的 CSS 类名不完整，根本原因不是配置漏写或插件没装，而是它的提取器压根没“看见”那些类名——静态分析机制决定了它只认写死在源码里的字面量字符串。
UnoCSS 默认不扫描变量拼接和运行时类名
它不会解析 class={`${base} ${isActive ? 'text-blue' : 'text-gray'}` 这种模板字符串，也不会跟踪 el.classList.add('hover:bg-black') 这类 DOM 操作。JSX 中的 className={`p-${size} rounded`}、Vue 的 :class="['text-sm', isActive && 'font-bold']" 同样被跳过。这些都不是静态字符串，构建时提取器无法还原出完整类名列表。
- 提取器只扫描
.vue、.ts、.jsx等文件中直接出现的类名字面量 - 变量、三元、数组解构、函数返回值中的类名，全部被忽略
- 即使类名是纯字符串常量，只要它定义在未纳入
content.filesystem的文件里（比如src/utils/icons.ts），也不会被扫描到
uno.config.ts 中的 safelist 是最直接的修复方式
当明确知道哪些动态类名一定会用到，又无法改写为静态形式时，safelist 就是兜底方案。它绕过提取逻辑，强制 UnoCSS 为列出的类生成 CSS 规则。
- 适用于图标类（如
i-carbon-favorite）、主题开关类（如dark:bg-gray-800）、尺寸映射类（如size-lg）等固定集合 - 支持 glob 模式：
'i-carbon-*'、'text-[#ff0000]' - 注意：
safelist不解决“类名拼错”问题，只确保已列出的类被生成；拼错仍需靠 TypeScript 枚举或 IDE 提示来预防
content.filesystem 配置遗漏导致类名“隐身”
UnoCSS 不会自动扫描整个项目，必须显式告诉它去哪些路径找类名。如果图标类写在 src/data/buttons.json，但 content.filesystem 只写了 ['src/**/*.{vue,ts}']，那 JSON 里的 text-red 就永远不会进最终 CSS。
立即学习“前端免费学习笔记（深入）”；
- 需要把工具函数、配置文件、JSON 数据、i18n 包等所有含类名的非模板文件都加进去
- 示例：
['src/**/*.{vue,ts,tsx,jsx}', 'src/utils/**/*.{ts,js}', 'src/data/**/*.json'] - 路径通配符要足够宽，尤其注意
.uvue（UniappX）、.astro等非标准后缀是否被覆盖
VSCode 提示失效也会让人误以为“类名不完整”
编辑器里没补全、没高亮，容易让人怀疑配置失败或类名不存在，其实只是提示链断了。UnoCSS 插件依赖两个条件：项目有有效的 uno.config.ts，且 VSCode 设置允许字符串内提示。
- 检查
.vscode/settings.json是否包含："editor.quickSuggestions": { "strings": true } - 确认已安装官方
UnoCSS插件，并在状态栏看到 UnoCSS 图标和版本号 - 重启 VSCode 或执行
Developer: Reload Window，避免缓存干扰
真正难处理的不是“类名不完整”，而是你根本不知道哪些类名没被识别——因为构建过程静默跳过，不报错也不警告。最可靠的做法是：构建后打开 dist/uno.css，搜索关键类名，确认是否存在；再对照源码定位它们的来源位置，判断该加 safelist 还是补 content.filesystem 路径。
