Webpack中启用CSS Modules需在css-loader的modules选项设为true或对象配置，推荐用auto: true自动识别.module.css文件；React中必须通过import的对象访问类名，不可硬编码字符串；@import、@keyframes、CSS变量等仍属全局作用域。
Webpack中如何配置css-loader启用CSS Modules
必须在 css-loader 的 modules 选项设为 true 或对象配置，否则 :local 不生效、类名不会哈希化。默认值是 false，这也是为什么很多人配了却没效果。
推荐写法（Webpack 5+）：
module: {
rules: [{
test: /\.module\.css$/,
use: [
'style-loader',
{
loader: 'css-loader',
options: {
modules: {
auto: true, // 只对 .module.css 自动启用，普通 css 不处理
localIdentName: '[name]_[local]_[hash:base64:5]'
}
}
}
]
}]
}
-
auto: true比手动用test: /\.module\.css$/更可靠——它按文件名（含.module）和import方式双重判断，避免漏配或误伤全局样式 -
localIdentName中的[hash:base64:5]足够防冲突，太长（如:8）会拖慢构建，太短（:3）在大型项目里有哈希碰撞风险 - 别把
modules: true直接写在全局/.css$/规则里——那样所有 CSS 都被模块化，第三方库样式（如antd）会失效
React中怎么导入和使用CSS Module类名
导入结果是 JS 对象，不是字符串；类名必须通过该对象的属性访问，硬写字符串类名（如 className="button"）一定不生效。
正确写法：
立即学习“前端免费学习笔记（深入）”；
// Button.module.css
.button {
background: #007bff;
}
.button--large {
padding: 12px 24px;
}
// Button.jsx
import styles from './Button.module.css';
function Button() {
return <button className={styles.button}>Click</button>;
}
- 支持组合：用
clsx或模板字面量拼接，如className={`${styles.button} ${props.size === 'large' ? styles['button--large'] : ''}` - 动态类名必须走对象属性，不能用
styles['button--' + size]这种计算属性——Webpack 在构建期静态分析，运行时拼接会导致类名未被收集，最终生成空字符串 - 如果用了
export（如:export { themeColor: #007bff; }），导出的是普通 JS 值，可直接当变量用，但不属于类名系统
为什么CSS Modules下全局样式仍可能泄漏
CSS Modules只作用于选择器本身，不处理 @import、@keyframes、伪元素内容、CSS 变量定义等——这些仍属全局作用域。
-
@import './reset.css'会把reset.css全部插入到当前模块作用域外，导致重置规则污染全局 -
@keyframes slideIn必须配合animation: slideIn 0.3s在同一模块内使用，否则浏览器找不到动画名 -
:root { --primary: #007bff; }是全局的，即使写在.module.css里；想局部化变量，得用& { --primary: #007bff; }包一层 - 伪元素
::before { content: "×" }的content值不会被哈希，但选择器本身（如.icon::before）会被模块化，所以只要类名正确，显示不受影响
与CSS-in-JS或Tailwind对比时的关键取舍点
CSS Modules 本质仍是 CSS 文件，它解决的是「命名」和「作用域」问题，不解决「复用逻辑」或「响应式开发效率」问题。
- 没有运行时样式计算开销，比 Emotion / Styled Components 构建更快、首屏更轻
- 无法像 Tailwind 那样通过原子类快速调整 margin/padding，每次改间距都得去改 CSS 文件、加新类、再改 JSX 引用
- 媒体查询必须写死在 CSS 里，没法像
useMediaQuery那样用 JS 控制条件渲染——但反过来，也意味着 SSR 更稳定，无水合错位风险 - 调试时 DevTools 显示的是哈希类名（如
Button_button__abc12），需打开 Source Map 并确保devtool: 'source-map'，否则定位困难
真正容易被忽略的是：CSS Modules 的「模块边界」仅由文件划分，跨文件复用类名（比如把 common.css 里的 .text-center import 到多个模块）仍会触发全局冲突——它不等于“自动 scoped”，只是让每个文件自成作用域。
