unocss与css modules共存时样式失效，根本原因是类名控制权冲突：css modules将类名哈希化或加属性选择器隔离，而unocss扫描原始字符串生成的规则无法匹配真实dom类名，导致匹配失败或优先级不足。
UnoCSS 和 CSS Modules 本身不直接冲突，但当它们同时作用于同一组件、尤其是类名被双重处理时，会出现样式失效、类名未生成、或 dev 模式正常而 build 后丢失等现象。核心问题不在“能否共存”，而在“谁控制了最终 class 名的生成与注入”。
为什么 class="text-red-500" 在 CSS Modules 组件里没生效？
这是最典型的表象：你在 .vue 或 .tsx 文件中写了 UnoCSS 原子类，但该文件启用了 scoped 或使用了 import styles from './Button.module.css' —— 此时 CSS Modules 已将所有类名哈希化（如 text-red-500 → text-red-500_abc123），而 UnoCSS 扫描到的仍是原始字符串 text-red-500，它生成的 CSS 规则匹配不到带哈希后缀的真实 class。
- CSS Modules 的
scoped模式会为每个 class 添加唯一属性选择器（如[data-v-xxx]），UnoCSS 生成的规则没有该属性，优先级天然更低 - 若你用的是
module.css+styles.textRed写法，则原子类根本不会出现在最终 HTML 中，UnoCSS 根本扫不到 - Vue SFC 中同时写
<style scoped></style>和<style></style>，后者可能被 UnoCSS 处理，但前者完全隔离，容易误判“样式丢了”
uno.config.ts 里要不要配 pipeline.content.include？
要，而且必须显式排除模块化样式文件。UnoCSS 默认扫描所有 .{vue,ts,jsx,html} 文件，如果 Button.module.css 被当成普通文本文件扫描，它里面出现的 text-red-500（比如注释、变量名、甚至路径字符串）会被误认为是原子类，导致无效规则注入，甚至构建报错。
- 在
uno.config.ts中明确限定扫描范围：include: ['src/**/*.{vue,ts,jsx,tsx,md}'] - 务必排除
*.module.css、*.module.scss等文件：exclude: ['**/*.module.*', '**/node_modules/**'] - 如果你用了
transformerAttributify，还要检查是否把styles.textRed这种 JS 属性访问误识别为类名——此时需配合blocklist过滤掉styles\.类模式
开发时能看到 __unocss 面板，但元素上没对应 class？
说明 UnoCSS 扫到了类名，也生成了规则，但这些规则没应用到目标元素上。常见原因不是配置错，而是 DOM 结构和作用域没对齐：
- 检查浏览器开发者工具中该元素的 computed styles，看是否有
text-red-500对应的声明被划掉（strikethrough）——大概率是 CSS 优先级输给了 scoped 样式或内联 style - 确认你没在组件内部用
<style scoped></style>定义了同名原子类（如.text-red-500 { color: red }），这会导致 UnoCSS 规则被覆盖 - 若使用了
shadcn-nuxt或其他基于 Tailwind 的组件库，注意其组件内部已写死 class，且常带!important；UnoCSS 默认不加!important，需手动在shortcuts或rules中加!text-red-500
真正棘手的点往往藏在“混合使用场景”里：比如一个 .vue 文件里既有 <template class="px-4"></template>（UnoCSS 处理），又有 <style scoped>.btn { ... }</style>（CSS Modules 处理），还有 import styles from './foo.module.css'（JS 导入）。这时候不是选一个方案，而是得明确每一处 class 的归属权——UnoCSS 只管它“认得出、扫得到、没被排除”的那部分。漏掉 exclude、混淆 scoped 与全局、或者高估了 UnoCSS 对 JS 字符串的识别能力，都会让排查变成盲人摸象。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
