CSS Modules
最后更新：2026-10-28
CSS Modules CSS Modules
CSS Modules 把普通 CSS 文件变成局部作用域：类名在构建时被编译成「文件名_类名_哈希」的唯一标识，组件之间天然隔离，告别全局样式污染。React 中以 styles.xxx 对象方式引用，是中大型项目的零成本样式隔离方案。
| 分组 | 生态与进阶 |
|---|---|
| 类型 | 模式 |
| 引入版本 | 社区标准方案，Vite / CRA / Next.js 均原生支持 |
ℹ️ 说明 编辑器将 JSX 转译为 JavaScript 后在沙箱中渲染真实界面；组件自动挂载，无需手写 render 调用。
📝 语法
/* 无需安装，Vite / Create React App 内置支持 */
/* Button.module.css —— 文件名必须带 .module.css */
.title { color: #0969da; }
.active { color: #1a7f37; }
// Button.jsx —— 类名通过 styles 对象引用
import styles from './Button.module.css'
export default function Button() {
return <button className={styles.title}>按钮</button>
}
// styles.title 编译为 'Button_title_x7s2k2'，全局唯一不冲突返回值：无返回值，CSS Modules 是构建期方案，用法说明见语法与示例。
▶ 示例
示例可直接运行：展开后自动渲染，编辑代码即时生效。
输出结果：
模拟演示：先展示 styles.card 与 styles.title 的「编译后哈希类名」，下方渲染一张卡片，点击「激活标题」按钮时标题会追加 active 哈希类名并变蓝色。真实项目中这些哈希类名由 .module.css 文件提供样式。💡 要点
💡 提示 文件名必须以 .module.css 结尾（.module.scss / .module.less 同理），否则会被当作全局样式。
ℹ️ 说明 CSS 里的类名建议写成 camelCase（titleColor），引用时直接 styles.titleColor，避免 styles['title-color'] 方括号写法。
⚠️ 注意 动态拼接 className 时注意用空格分隔多个类名，漏掉空格会导致两个类都失效。
🏷️ 生态与进阶相关
💡 相关案例
更多案例整理中，敬请期待。
📚 相关教程
❓ 常见问题
Q CSS Modules 和普通 CSS 有什么区别？
A 普通 CSS 的类名是全局的，同名会互相覆盖；CSS Modules 在构建时把类名编译成「文件名_类名_哈希」的唯一标识，样式只作用于引用它的组件，天然隔离。
Q 想写全局样式怎么办？
A 用 :global 包裹，例如 :global(.ant-btn) { … }；或另建一个不带 .module 的普通 css 文件，其中类名保持全局。
Q styles 里引用不存在的类名会报错吗？
A 运行时不报错，styles.xxx 为 undefined，元素只是丢失类名，容易排查困难。TypeScript 项目可生成 .d.ts 类型文件，在编译期就发现拼写错误。
