根本原因是webpack未将.module.less识别为css模块,必须同时满足三要素:文件名严格为.module.less、webpack配置中声明lessmoduleregex并置于oneof规则首位、使用兼容的less-loader@7.3.0(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。常见断点:
-
webpack.config.js里没定义lessModuleRegex = /\.module\.less$/ - 匹配规则写在了普通
lessRegex规则之后,被提前捕获跳过 -
less-loader版本 >7.3.0(比如用了 v10+),但项目是 CRA v4(Webpack 4),触发this.getOptions is not a function错误,整个链路静默失败 -
getStyleLoaders调用时漏传modules: { getLocalIdent: getCSSModuleLocalIdent },或importLoaders不够(Less 里有@import时至少要设为2)
如何让 import './X.module.less' 正常返回样式对象?
以 CRA eject 后的 Webpack 配置为例,关键三步必须同时满足:
- 在 config 头部加:
const lessModuleRegex = /\.module\.less$/; - 在
oneOf数组最前面插入模块规则(顺序不能错):{ test: lessModuleRegex, use: getStyleLoaders( { importLoaders: 2, sourceMap: isEnvDevelopment, modules: { mode: 'local', getLocalIdent: getCSSModuleLocalIdent, }, }, 'less-loader' ), } - 降级
less-loader到@7.3.0:npm install less-loader@7.3.0 --save-dev(CRA v4/v5 必须)
第三方库(如 Ant Design)的 Less 文件被意外模块化怎么办?
Ant Design 的 @import '~antd/lib/style/themes/default.less' 如果进了 .module.less 链路,变量、mixin 全被哈希,.ant-btn 类名失效。解决方式很直接:
- 确保
node_modules路径被排除在模块规则外:exclude: /node_modules/加到lessModuleRegex规则里 - 不要在
.module.less中@import第三方库的完整样式文件;改用按需引入 +:global()包裹,例如:.my-button { :global(.ant-btn) { margin-right: 8px; } } - 全局主题变量仍可放在单独的
common.less中,用style-resources-loader注入,但它不能是.module.less
Less 语法在 CSS Modules 下的硬限制
composes 是 CSS Modules 的关键字,Less 解析器不认识它,写进去直接报 ParseError: Unexpected token 'composes'。其他容易踩坑的点:
-
calc()在 Less 里会被提前计算,比如width: calc(100% - 10rem)可能变成calc(90%),必须写成width: calc(~"100% - 10rem") - 背景图路径在
.module.less中相对定位会错乱,推荐用~"url(./icon.png)"或退一级写url(../assets/icon.png) -
&__header这种嵌套写法编译后仍是全局类名,不等于 CSS Modules 的作用域隔离——它只是 BEM 命名,没加[data-react-root]这类属性选择器
真正卡住的从来不是 Less 语法,而是构建配置里那几行正则和 loader 顺序。一旦 .module.less 没被正确识别,后面所有样式写法都白搭。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











