如何解决React中CSS Modules与Less冲突

根本原因是Webpack未将.module.less识别为CSS模块，必须同时满足三要素：文件名严格为.module.less、Webpack配置中声明lessModuleRegex并置于oneOf规则首位、使用兼容的[email protected]（CRA v4必需）。

React 项目里 import styles from './Button.module.less' 返回空对象，或者类名没被哈希、依然全局生效——根本不是 Less 写法问题，而是构建链路没把 .module.less 当作 CSS Modules 处理。

为什么 .module.less 不走 CSS Modules 流程？

Webpack/Vite 默认只识别 .module.css 和 .module.scss，.module.less 必须显式配置才能接入 css-loader?modules。常见断点：

1. webpack.config.js 里没定义 lessModuleRegex = /.module.less$/
2. 匹配规则写在了普通 lessRegex 规则之后，被提前捕获跳过
3. less-loader 版本 >7.3.0（比如用了 v10+），但项目是 CRA v4（Webpack 4），触发 this.getOptions is not a function 错误，整个链路静默失败
4. getStyleLoaders 调用时漏传 modules: { getLocalIdent: getCSSModuleLocalIdent }，或 importLoaders 不够（Less 里有 @import 时至少要设为 2）

如何让 import './X.module.less' 正常返回样式对象？

以 CRA eject 后的 Webpack 配置为例，关键三步必须同时满足：

1. 在 config 头部加：const lessModuleRegex = /.module.less$/;
2. 在 oneOf 数组最前面插入模块规则（顺序不能错）：

   {test: lessModuleRegex,use: getStyleLoaders({importLoaders: 2,sourceMap: isEnvDevelopment,modules: {mode: 'local',getLocalIdent: getCSSModuleLocalIdent,},},'less-loader'),}

3. 降级 less-loader 到 @7.3.0：npm install [email protected] --save-dev（CRA v4/v5 必须）

第三方库（如 Ant Design）的 Less 文件被意外模块化怎么办？

Ant Design 的 @import '~antd/lib/style/themes/default.less' 如果进了 .module.less 链路，变量、mixin 全被哈希，.ant-btn 类名失效。解决方式很直接：

1. 确保 node_modules 路径被排除在模块规则外：exclude: /node_modules/ 加到 lessModuleRegex 规则里
2. 不要在 .module.less 中 @import 第三方库的完整样式文件；改用按需引入 + :global() 包裹，例如：

   .my-button {:global(.ant-btn) {margin-right: 8px;}}

3. 全局主题变量仍可放在单独的 common.less 中，用 style-resources-loader 注入，但它不能是 .module.less

Less 语法在 CSS Modules 下的硬限制

composes 是 CSS Modules 的关键字，Less 解析器不认识它，写进去直接报 ParseError: Unexpected token 'composes'。其他容易踩坑的点：

1. calc() 在 Less 里会被提前计算，比如 width: calc(100% - 10rem) 可能变成 calc(90%)，必须写成 width: calc(~"100% - 10rem")
2. 背景图路径在 .module.less 中相对定位会错乱，推荐用 ~"url(./icon.png)" 或退一级写 url(../assets/icon.png)
3. &__header 这种嵌套写法编译后仍是全局类名，不等于 CSS Modules 的作用域隔离——它只是 BEM 命名，没加 [data-react-root] 这类属性选择器

真正卡住的从来不是 Less 语法，而是构建配置里那几行正则和 loader 顺序。一旦 .module.less 没被正确识别，后面所有样式写法都白搭。