HTML中CSS模块化:CSS Modules完整版

说实话，CSS Modules 一直是原生 HTML 项目里实现真正作用域隔离的最稳方案。它不是“可选项”，而是“该用就用”——尤其是当你需要在多个页面复用同一个类名（比如 .btn），既不想手动加前缀，又不想因为一点样式隔离就把整个构建工具全家桶搬进来的时候，它几乎是最优解。

为什么不用 BEM 或命名空间就能解决样式冲突？

重点来了，CSS Modules 怎么做到的呢？不是靠开发者拼命记住命名规则，而是让构建工具自动帮你重命名 class。你在源文件里写 .button，编译之后它自动变成类似 _button_1x2y3 这样的唯一标识，天然就能避免全局污染。这种方式的好处很明显：

• 不再依赖团队成员自觉遵守 BEM 规则，特别适合协作开发或者接手旧项目
• 不用手动拼接出 header__na v--active 这种长字符串，写法更轻量
• 支持局部变量和 :global() 按需穿透，比纯 CSS-in-JS 方案更贴近传统工作流
• 需要特别注意的是：它必须配合构建工具（比如 Webpack 或 Vite）使用，如果你只是纯 HTML 页面引入 .css 文件，那根本不起作用

Webpack 中启用 CSS Modules 的最小配置要点

配置这件事，关键不是加一大堆 loader，而是确保 css-loader 的 modules 开关是打开的，并且路径匹配要正确。这里有几个容易踩坑的点：

• 匹配规则一定要排除 node_modules 和公共样式文件（比如 common.css），否则第三方库的样式会出问题
• modules: true 是最基础的配置，但建议显式加上 localIdentName 来控制生成的名字，比如 [name]_[local]_[hash:6]，这样在调试时更友好
• 如果项目中用了 Sass 或 Less，css-loader 必须放在 sass-loader 或 less-loader 的后面，顺序搞错了的话，class 就不会被处理
• 别忘了配 MiniCssExtractPlugin.loader（生产环境）或 style-loader（开发环境），否则样式不会生效

HTML 中怎么引用 CSS Modules 生成的 class？

这一点很容易让人犯迷糊：你不能再直接往 HTML 里写 class="button"了 —— 那个名字在运行时已经不存在了。必须通过 JS 来加载模块，然后把真正的 class 注入到 DOM 中。

• 在 .jsx 或 .tsx 中：import styles from './Button.module.css';，然后使用 className={styles.button}
• 如果场景是纯 HTML + JS，可以用 import('./Button.module.css').then(css => { ... }) 动态加载，再通过 document.body.classList.add(Object.values(css)[0])（不过这种方法不推荐，会破坏语义）
• 常见错误有两种：一种是写了 import './Button.module.css'（没有解构），结果 class 名字丢了；另一种是误以为 require 返回的是字符串，但实际上返回的是对象
• 如果非要在纯 HTML 下用，不如退回到 css-loader + style-loader + locals 模式，配合 getLocalIdent 自定义逻辑，但说实话，复杂度会陡增

容易被忽略的边界问题

模块化不是万能胶，有几个硬伤得提前知道，不然调试起来会让人头大：

• @import 在 .module.css 中默认不触发模块化 —— 被 import 进来的文件仍然按全局处理，除非它自己也声明为 .module.css
• 动画关键帧（@keyframes）名不会被哈希处理，必须手动加 :global() 包裹，否则动画会找不到目标
• 如果涉及服务端渲染（SSR），class 名前后端必须保持一致，否则 React 的 Hydration 会报 mismatch，需要统一配置 exportLocalsConvention
• 在 DevTools 里看到的 class 名是哈希值，调试时别盯着它去改样式 —— 改源文件，刷新就行

真正卡住人的从来不是“怎么配置”，而是你还没想清楚：这个模块到底该暴露哪些 class 给外部？要不要留一个 :global(.reset)？动画要不要单独抽成一个文件？这些设计决策，比 loader 配置要重要得多。