CSS Modules 通过构建时自动哈希类名实现作用域隔离，需配合打包工具配置启用，导入为对象并用 styles.xxx 使用，确保样式不冲突且可维护。
怎么让同一个类名在不同组件里互不干扰
CSS Modules 的核心作用就是自动给类名加哈希后缀，让 .button 在组件 A 里变成 _button_abc123，在组件 B 里变成 _button_def456。它不是靠约定或文档约束，而是构建时硬编码隔离。
必须配合打包工具（如 Webpack、Vite）使用，纯 HTML 引入 .css 文件不会生效。开启方式取决于构建配置：css-loader 要加 modules: true；Vite 默认对 .module.css 后缀启用模块化。
- 文件命名必须是
xxx.module.css（Vite）或显式配置modules: true（Webpack），否则当普通 CSS 处理 - 不能用
@import导入全局 CSS 到模块文件里，会破坏作用域；要用:global(.xxx)显式声明需穿透的样式 - 动态拼接类名（如
className={style['btn-' + type]}）要确保键名在模块对象中真实存在，否则运行时是undefined
React 里怎么正确用 CSS Modules 的类名
导入的是一个 JS 对象，不是字符串，所以不能直接写 className="button"。必须通过对象属性访问，比如 className={styles.button}。这是最容易漏掉的一步，错写成字符串就等于没用上模块化。
常见错误现象：样式完全不生效，或者所有组件共用同一套全局类名，冲突照旧。检查控制台元素面板，看最终渲染出的 class 属性是不是带哈希值，不是的话说明没走模块化流程。
- 导入写法固定为
import styles from './Button.module.css'，不能用import * as styles或默认导出别名 - 支持驼峰式类名（如
.btnPrimary），但 CSS 文件里仍要写连字符格式（.btn-primary），JS 中通过styles.btnPrimary访问 - 如果组件需要透出根元素类名（比如供父组件定制），得用
:global()包一层，否则外部无法通过类名定位
为什么 CSS Modules 生成的类名这么长
哈希长度不是随意的，它由文件路径 + 类名 + 本地作用域内容共同决定。改一行 CSS、换一个文件位置，都可能导致哈希变化。这不是 bug，是设计使然——目的是确保“样式即模块”，内容变则标识变，避免缓存误命中。
开发时类名太长确实影响调试，但生产环境不影响性能：浏览器只认最终字符串，跟长度无关；打包工具也不会因此增加体积（哈希是编译期替换，不额外存映射表）。
- 可通过
localIdentName配置缩短（如[hash:base64:5]），但不建议在团队项目中随意改，容易导致协作时哈希不一致 - Vite 用户注意：v4.3+ 默认启用
scopeBehaviour: 'strict'，子组件样式不会继承父组件模块作用域，和 Webpack 行为略有差异 - 服务端渲染（SSR）场景下，必须保证客户端与服务端使用完全相同的哈希生成逻辑，否则样式丢失
和 CSS-in-JS、Tailwind 比，CSS Modules 卡在哪
它不处理原子类、不提供主题变量注入、也不支持运行时条件样式计算。它的边界很清晰：只解决「类名作用域」这一个问题。想实现暗黑模式切换？得靠 JS 控制 className 切换两套模块；想复用间距数值？得靠 CSS 自定义属性或 JS 导出常量。
兼容性没问题，所有现代打包工具都支持，但和 PostCSS 插件配合时要注意顺序：postcss-modules 必须在 autoprefixer 之前，否则 :global 语法可能被误处理。
- 不能直接在
style属性里用styles.xxx，那是类名字符串，不是样式对象；要用className - 没有内置的媒体查询封装，
@media (min-width: 768px)还得手写，不像 Emotion 支持对象写法 - 和 TypeScript 配合时，建议加
declare module '*.module.css'声明，否则styles.xxx会报类型错误
真正难的不是配置，是团队对“哪些该进模块、哪些该抽成全局”的判断。一个按钮组件的 .icon 类要不要模块化？如果图标样式被其他组件复用，又不想暴露具体实现，就得权衡是提成独立模块，还是用 :global() 约定接口。这种边界问题，工具帮不上忙。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
