CSS Modules 通过构建时将类名重命名为哈希唯一值（如 Button_button__kx8rA）实现局部作用域，避免全局污染；仅 class/id 选择器被处理，@keyframes 等仍全局，需手动隔离。
为什么 CSS Modules 能防止全局样式污染
CSS Modules 不是新语法，而是构建工具（如 Webpack、Vite）在编译时对 .module.css 文件做的局部作用域处理：它把每个类名自动重命名为带哈希的唯一标识（比如 Button_button__kx8rA），并只在对应组件内暴露这个映射关系。这意味着即使两个组件都写了 .title，它们最终生成的 CSS 类名完全不同，自然互不干扰。
- 构建时重命名仅作用于
class和id选择器，@keyframes、@font-face等仍为全局，需手动加前缀或用:global() -
:global(.btn)内部的样式会逃逸出模块作用域，慎用 - 类名映射只在 JS 中通过
import styles from './Button.module.css'可访问，HTML 模板里写死的class="title"不生效
如何正确导入和使用 CSS Modules 类名
关键不是“写对 CSS”，而是“JS 怎么读取并应用”。直接写 className="button" 是无效的，必须走模块导出的对象。
// Button.module.css
.button {
background: #007bff;
}
.button:hover {
opacity: 0.8;
}
对应组件中必须这样用：
import styles from './Button.module.css';function Button() { return ; }
- 文件名必须含
.module.css（或.module.scss等），否则构建工具不会启用 CSS Modules 处理 -
import styles是默认导出对象，键名为原始类名，值为转换后的唯一字符串 - 不支持
classNames(styles.button, 'extra-class')这种混用——'extra-class'是全局类，可能冲突或未定义
嵌套、组合与动态类名怎么写
CSS Modules 原生支持 composes 组合和 :local 显式声明局部作用域，但不支持 SASS 那样的深度嵌套（需靠构建插件或改用 postcss-nested）。
立即学习“前端免费学习笔记（深入）”；
-
composes: theme from './theme.module.css';可复用其他模块的样式，且组合后仍是局部作用域 - 动态类名推荐用逻辑拼接：
className={`${styles.button} \${isActive ? styles.active : ''}`}，避免用classnames库引入额外依赖 -
:local(.icon) { ... }和不加:local效果一致；:global(.reset) { ... }才真正脱离模块约束
Vite 或 Webpack 下常见报错与修复
最常遇到的是「样式没生效」或「控制台警告 Module not found」，基本都指向路径或配置问题。
- Vite 默认支持
.module.css，但若用了css.modules.localsConvention = 'camelCase'，则.my-button会映射为styles.myButton，注意命名一致性 - Webpack 需确认
css-loader配置中modules: true或modules: { mode: 'local' } - 报错
TypeError: Cannot read property 'xxx' of undefined：多半是 import 路径错、文件名没带.module、或组件里用了未定义的styles.xxx - 热更新失效？检查是否误将 CSS 文件放在
public/目录下——那里不走模块处理流程
真正容易被忽略的点是：CSS Modules 只解决类名冲突，不解决 CSS 优先级问题。两个模块里都写了 .button { color: red; } 和 .button { color: blue; }，谁在后面加载谁生效——顺序由 JS import 顺序决定，不是 CSS 文件位置。
