CSS Modules通过构建时哈希重命名类名实现局部作用域，仅对.module.css文件生效，支持:global显式声明全局样式，零运行时开销且SSR友好。
为什么全局样式会互相覆盖
CSS 默认是全局作用域，.btn 这种类名一旦在多个组件里出现，后加载的样式就会覆盖先加载的。常见错误现象是：改了一个按钮颜色，另一个页面的按钮也变了；或者第三方 UI 库的 .modal 和你自己写的 .modal 冲突，弹窗布局错乱。
根本原因不是写法错，而是 CSS 本身没模块概念。Webpack 或 Vite 默认打包时，所有 .css 文件都合并进同一个样式表，浏览器只认选择器优先级和加载顺序。
- 全局类名冲突无法靠命名规范彻底避免（比如团队协作时，
.header这种基础名太容易重复） -
!important是临时止痛药，会让后续维护越来越难 - BEM 命名能缓解但不解决本质问题——它仍依赖人工约定，且无法阻止第三方样式入侵
CSS Modules 是怎么做到“局部作用域”的
它不是新语法，而是构建工具（如 Webpack 的 css-loader）在编译阶段把类名自动哈希重命名。你写的 .button 会被转成类似 _button_abc123 这样的唯一标识，同时 JS 中通过 import styles from './Button.module.css' 拿到映射对象。
关键点在于：这个转换发生在构建时，运行时完全不依赖 JS 注入或 Shadow DOM。
- 只对
.module.css（或.module.scss等）后缀文件生效，普通.css仍是全局 - 类名哈希默认包含文件路径和原始类名，所以同名但不同文件的
.icon会生成不同哈希 - 支持
:global(.btn)显式声明全局样式，适合覆盖第三方库或重置样式
示例：
/* Button.module.css */
.button {
background: blue;
}
:global(.legacy-modal) {
z-index: 9999;
}JS 中使用：styles.button 对应哈希后的真实类名，而 .legacy-modal 保持原样输出。
和 CSS-in-JS、Shadow DOM 的实际区别在哪
很多人以为 CSS Modules 是“把 CSS 写进 JS”，其实它只是 JS 和 CSS 的绑定关系，样式依然输出为独立 <style> 标签，不增加运行时开销。
- 对比 CSS-in-JS（如 styled-components）：
styled.div 会在运行时生成样式并插入 <head>，有性能损耗，服务端渲染需额外处理；CSS Modules 零运行时，SSR 友好
- 对比 Shadow DOM：
attachShadow 确实隔离彻底，但破坏了常规样式继承（比如 font-family 不会透传），且不兼容老浏览器；CSS Modules 无兼容性问题，所有现代构建工具都原生支持
- 注意：CSS Modules 无法解决 HTML 结构导致的样式穿透（比如父组件设了
div * { color: red }，子组件文字仍会变红），它只管类名作用域
容易被忽略的配置细节和坑
很多项目开了 CSS Modules 却还是有冲突，问题常出在配置漏项或理解偏差。
- Webpack 中必须给
css-loader 加 modules: true，Vite 默认开启但仅限 .module.css 后缀，写成 index.css 就无效
- 如果用了 Sass，确保
scss-loader 在 css-loader 之前，否则 @use 或 @forward 可能失效
- 动态 class 绑定别直接拼字符串：
className="button ${isPrimary ? 'primary' : ''}" 会失败，因为 primary 不在 styles 对象里；正确写法是 className={`${styles.button} \${isPrimary ? styles.primary : ''}`}
- 服务端渲染时，如果样式未提前注入，首屏可能闪动——需要搭配
collectStyles 或类似方案提取 CSS 字符串
styled.div 会在运行时生成样式并插入 <head>，有性能损耗，服务端渲染需额外处理；CSS Modules 零运行时，SSR 友好attachShadow 确实隔离彻底，但破坏了常规样式继承（比如 font-family 不会透传），且不兼容老浏览器；CSS Modules 无兼容性问题，所有现代构建工具都原生支持div * { color: red }，子组件文字仍会变红），它只管类名作用域- Webpack 中必须给
css-loader加modules: true，Vite 默认开启但仅限.module.css后缀，写成index.css就无效 - 如果用了 Sass，确保
scss-loader在css-loader之前，否则@use或@forward可能失效 - 动态 class 绑定别直接拼字符串：
className="button ${isPrimary ? 'primary' : ''}"会失败，因为primary不在styles对象里；正确写法是className={`${styles.button} \${isPrimary ? styles.primary : ''}`} - 服务端渲染时，如果样式未提前注入，首屏可能闪动——需要搭配
collectStyles或类似方案提取 CSS 字符串
CSS Modules 解决的是“类名污染”这个具体问题，不是万能样式方案。它不管优先级计算、不管响应式断点组织、也不管设计系统 token 管理。用对地方，它就安静地待在构建流程里，不声不响把类名隔开。
立即学习“前端免费学习笔记（深入）”；
