CSS天然无作用域，.button会全局生效导致样式冲突；CSS Modules通过构建时重命名（如Button_button__abc123）并限定作用域解决，需.module.css后缀、JS导入使用，且仅转换顶层类名。
为什么直接写 .button 会污染全局样式
因为浏览器不区分 CSS 是谁写的，所有 .button 类名都会被合并进同一张样式表。你改了组件 A 的 .button，组件 B 里同名类可能突然变宽、变色甚至消失——尤其在多人协作或接入第三方 UI 库时，这类问题几乎必然发生。
根本原因不是“写错了”，而是 CSS 天然没有作用域概念。不加干预，.button 就是全局变量。
常见错误现象：
- 开发时样式正常，打包后某个按钮莫名继承了其他模块的 margin
- npm install 后，项目里所有 .modal 都变窄了（因为新依赖也定义了同名类）
- 使用 !important 临时压住冲突，结果越压越乱
CSS Modules 是怎么让类名自动局部化的
它不是魔法，本质是在构建阶段把你的 .button 编译成类似 Button_button__abc123 这样的唯一字符串，并只让这个字符串在当前组件内生效。
关键点：
- 必须配合构建工具（如 Webpack、Vite）启用 css-modules 模式
- 文件名需带 .module.css 后缀（例如 Button.module.css），否则不触发转换
- 类名必须通过 JS 对象导入使用，不能直接写死在 HTML 中
示例：
/* Button.module.css */<br>.button {<br> background: blue;<br> padding: 8px;<br>}// Button.jsx<br>import styles from './Button.module.css';<br>export default function Button() {<br> return <button className={styles.button}>Click</button>;<br>}
立即学习“前端免费学习笔记（深入）”；
遇到 Module not found: Can't resolve './xxx.module.css' 怎么办
这说明构建工具没识别出 CSS Modules 配置，不是文件路径错了。
检查项：
- Vite 项目：确认 vite.config.js 中未禁用 css.modules（默认开启，但若显式配置了 css: { modules: false } 就会关闭）
- Webpack 项目：确认 module.rules 里针对 .module.css 的 rule 启用了 modules: true，且 loader 顺序正确（css-loader 必须在 style-loader 前）
- Next.js：从 13.2 起默认支持，但若用 app/ 目录，必须用 client component 才能 import 样式文件；server component 不允许 import CSS
类名哈希太长影响调试和可读性
默认生成的 Button_button__abc123 确实难读，但没必要手动改——调试时浏览器开发者工具里依然能看到原始类名注释，比如：<button class="Button_button__abc123">
旁边 CSS 面板会显示来源是 Button.module.css:2，点击就能跳转。
如果真要缩短，可在构建配置中调整 localIdentName：
- Webpack：css-loader 的 options.modules.localIdentName 设为 [name]_[local]_[hash:4]
- Vite：css.modules.generateScopedName 支持相同语法
但注意：哈希位数过少（如 [hash:2]）在大型项目中可能冲突，导致样式错乱
真正容易被忽略的是：CSS Modules 只处理顶层类名，嵌套选择器（如 .button span）里的 span 不会被转换，它仍依赖 DOM 结构——所以别指望靠嵌套规避全局污染，该拆组件还得拆
