css modules本质是构建时类名重命名机制，未正确配置构建工具（如vite禁用modules、webpack未设css-loader modules: true、文件名非button.module.css）会导致.button无法变为button_button__abc123。
CSS Modules 不是“写法问题”，而是构建阶段的类名重命名机制——没配对构建工具，.button 就永远只是 .button，不会变成 Button_button__abc123。
为什么 import styles from './Button.module.css' 报错 “Module not found”
这不是路径写错了，而是构建工具根本没把该文件识别为 CSS Modules。
- Vite 项目：检查
vite.config.js是否显式关闭了模块化，比如写了css: { modules: false }；默认是开启的，但一禁就全失效 - Webpack 项目：确认
module.rules中处理.module.css的 rule 里，css-loader配置了modules: true（或{ mode: 'local' }），且css-loader必须在style-loader之前 - Next.js App Router：必须在 Client Component（加
'use client'）中import，Server Component 禁止导入任何 CSS 文件 - 文件名必须严格是
Button.module.css，不是Button.css或button.Module.css（大小写敏感）
类名没变、样式全局泄漏的常见原因
即使文件名和配置都对，也可能因为写法绕过了模块化逻辑。
- 直接在 JSX 中写死
className="button"—— 这完全跳过styles.button映射，button就是全局字符串 - 用
composes引入了非模块化 CSS 文件（比如@import './reset.css'），被 import 的文件不会被局部化 - 在
:global()外写了后代选择器，例如.container .item：两个类名各自哈希后，选择器无法匹配，但若其中某个类恰好全局存在，反而可能意外生效 - 动态拼接类名，如
className={`${styles.button} ${otherClass}`，其中otherClass是字符串而非styles对象属性，就会引入非局部类
:global() 怎么用才不破环局部性
:global() 是唯一能“逃出”模块化的出口，但它的作用范围极窄，容易误用。
- 只对括号内紧邻的选择器生效：
:global(.btn) .icon中，.btn全局，.icon仍被局部化 - 要全局组合，必须整个包裹：
:global(.modal .modal-body)，不能拆成:global(.modal) :global(.modal-body)（后者等价于两个独立全局类） -
@keyframes和@media内部不能直接写:global()；需把要全局的类名提到外层声明，再在动画/媒体查询里引用 - 滥用
:global(.header)会直接复现老式全局污染问题，建议仅用于对接遗留样式或第三方 UI 库
哈希类名太长影响调试怎么办
生成的 Button_button__abc123 确实难读，但没必要改配置去缩短它。
- 现代浏览器开发者工具（Chrome/Firefox）在 Elements 面板中 hover 类名时，会显示原始类名注释，比如
/* .button */ - 如果真要调整哈希规则，Webpack 可配
localIdentName，Vite 可设css.modules.generateScopedName，但去掉[local]或[hash]会破坏局部性，不推荐 - 真正影响调试的是嵌套写法失效（如
.container .item）——应改用:hover、&（Sass）或composes复用，而不是靠缩短哈希来“假装可读”
最常被忽略的一点：CSS Modules 的作用域隔离，只发生在「构建时类名重命名 + JS 对象引用」这个闭环里。只要任一环节断开（比如手写 class 字符串、漏掉 .module 后缀、loader 顺序错位），就退回全局污染状态——它不靠语法约束，而靠工程链路的严丝合缝。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
