CSS Modules 失效的六大原因：文件命名错误、动态类名未用 styles.xxx、全局选择器污染、第三方组件样式无法控制、:global() 作用范围误解、作用域未严格锚定。
为什么直接写 .btn 或 h3 必然导致冲突
浏览器不认“你在哪个文件里写的”，只按选择器是否匹配、权重高低、加载顺序来应用样式。.btn 在 header.module.css 和 footer.module.css 里各定义一次，后加载的那个就生效——这不是 bug，是 CSS 的根本行为。更危险的是 h3 这类标签选择器，它会无差别命中所有页面里的 h3，哪怕你只是想改某个卡片里的标题。
.module.css 文件名写错，CSS Modules 就完全不工作
构建工具（Vite/Webpack/Next.js）只对严格匹配 .module.css（或 .module.scss 等）的文件启用模块化逻辑。其他命名一律当普通 CSS 处理，.button 就永远是 .button，不会变成 Button_button__abc123。
-
Button.css→ 全局，Modules 不生效 -
button.Module.css→ 后缀大小写错误，Vite 默认不识别 -
Button.module.scss→ 正确，但需确保sass-loader在css-loader之前 - Vite 用户检查
vite.config.js是否显式写了css: { modules: false } - Webpack 用户确认
css-loader配置含modules: true，且没被覆盖
动态拼接类名时，className="button" 是最常见失效点
写了 import styles from './Button.module.css'，但 JSX 中写 className="button"，等于完全绕过 Modules 映射——那个字符串就是全局的 button，和模块毫无关系。
- ✅ 正确：
className={styles.button} - ❌ 错误：
className="button"、className={`button ${styles.icon}`（前半段是全局） - 动态组合推荐用
clsx：className={clsx(styles.button, hasIcon && styles.withIcon)} -
:global()只作用于括号内紧邻的选择器：:global(.ant-btn) .icon中只有.ant-btn全局，.icon仍被局部化
第三方组件 DOM 不在你的控制范围内
像 Ant Design、Element Plus 这类库，内部 DOM 结构和 class 名（如 .el-input__inner）是硬编码的，不会被你的 .module.css 处理。你写的 .el-input__inner { border: 1px solid red } 如果没加限定，就会污染所有地方。
立即学习“前端免费学习笔记（深入）”；
- 安全做法：在外层容器加唯一 data 属性，如
<div data-scope="user-form">，再写 <code>[data-scope="user-form"] .el-input__inner - 避免模糊匹配：
[class^="el-"]比[class*="el-"]更精准，后者可能误中my-element -
:deep()（Vue）或:global()（React + Modules）只能穿透到子组件已渲染的节点，对dangerouslySetInnerHTML插入的 HTML 无效
真正麻烦的不是规则多，而是总有人觉得“就改一个
margin，没必要套三层”。等上线发现 .card__title 被另一处 .article-title 的 margin-top 撑开，才明白：隔离效果不取决于你写了多少 __ 和 --，而取决于所有相关样式是否从源头就被锚定在同一个作用域边界里。
