CSS模块化本质是作用域隔离，需构建工具配置modules: true并正确导入；文件名匹配.module.css、区分全局/模块规则、JS中通过styles.xxx引用类名，嵌套与动画需手动处理。
什么是 CSS 模块化：不是加个 module 后缀就完事了
CSS 模块化本质是**作用域隔离**，目标是让每个组件的样式只影响自己，不污染全局。常见误解是以为给文件起名 Button.module.css 就自动模块化了——实际必须配合构建工具（如 Webpack、Vite）和正确的导入方式才能生效。原生 CSS 无模块机制，:scope 或 @layer 也解决不了组件级封装问题。
Webpack 中启用 CSS Modules 的关键配置
在 webpack.config.js 的 module.rules 里，必须显式启用 modules: true，且不能与全局 CSS 规则混用：
module: {
rules: [
{
test: /\.module\.css$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
modules: true, // 必须开启
localsConvention: 'camelCase' // 可选：支持驼峰命名引用
}
}
]
},
{
test: /\.css$/,
exclude: /\.module\.css$/,
use: ['style-loader', 'css-loader'] // 全局 CSS 单独处理
}
]
}
-
test: /\.module\.css$/是触发模块化的开关，文件名必须匹配 - 漏掉
exclude会导致全局 CSS 被误判为模块，class 名被哈希化，页面样式崩坏 -
localsConvention: 'camelCase'允许你在 JS 中写styles.buttonPrimary而非styles['button-primary']
React 中使用 CSS Modules 的正确姿势
导入时必须用 import styles from './Button.module.css'，不能用 import './Button.module.css'（后者会加载但不返回类名映射）：
import React from 'react';
import styles from './Button.module.css';
const Button = ({ children }) => (
<button className={styles.button}>{children}</button>
);
export default Button;
- JSX 中所有 class 都要通过
styles.xxx引用，硬编码className="button"会失效 - 组合多个 class 用
className={`${styles.button} ${styles.primary}`}或clsx库 - 动态 class 切换必须判断后拼接，
styles[status]这种写法只有在localsConvention开启时才安全
容易被忽略的边界问题：嵌套、动画与全局覆盖
CSS Modules 默认只作用于顶层选择器，对 & 嵌套、@keyframes 和伪类仍需手动处理：
立即学习“前端免费学习笔记（深入）”；
-
&:hover有效，但.parent &会脱离模块作用域，变成全局污染 -
@keyframes名称不会被模块化，必须手动加前缀或改用animationName动态注入 - 需要穿透全局样式（如重置第三方组件）时，得用
:global(.third-party-button)显式声明，否则无效 - 服务端渲染时，若未同步生成 class 映射，会出现水合不匹配（hydration mismatch）错误
模块化不是银弹，它把「命名冲突」问题转成了「引用繁琐」和「动态样式管理」问题，真正提升可维护性的关键是团队约定 + 工具链统一 + 对副作用保持敏感。
