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，和模块毫无关系。

CSS工具箱(专业版)

全功能 CSS 工程手册，覆盖性能优化、无障碍、设计系统与跨浏览器兼容。

下载

• ✅ 正确：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 属性，如
  ，再写 [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 撑开，才明白：隔离效果不取决于你写了多少 __ 和 --，而取决于所有相关样式是否从源头就被锚定在同一个作用域边界里。