如何配置React的CSS Modules支持Less变量

作者：袖梨 2026-08-13

根本原因是 Webpack 未将 .module.less 当作 CSS Module 处理，因规则顺序错误或 less-loader 版本不兼容（如 CRA v4 需用 [email protected]），导致 css-loader 未启用 modules，styles 返回空对象。

为什么 import styles from './X.module.less' 返回空对象？

根本原因不是 Less 语法写错了，而是 Webpack 根本没把它当 CSS Module 处理——它被普通 .less 规则捕获了，跳过了 css-loader 的 modules: true 流程。必须同时满足三个硬性条件：文件名必须是 X.module.less、Webpack 配置中存在精确匹配 /.module.less$/ 的规则、该规则里 css-loader 显式启用了 modules 并传了 getLocalIdent。

如何让 .module.less 同时支持 CSS Modules + Less 变量？

关键在 getStyleLoaders 调用时的参数组合：模块化规则必须用 less-loader + css-loader?modules + postcss-loader 三件套，且 less-loader 的配置要能透传变量。常见错误是把 modifyVars 写在错层（比如塞进 css-loader 选项里）。

在 webpack.config.js 的 oneOf 数组中，.module.less 规则必须排在普通 .less 规则之前
use 链里，less-loader 的 lessOptions 必须包含 javascriptEnabled: true 和 modifyVars，例如：{ javascriptEnabled: true, modifyVars: { '@primary-color': '#1DA57A' } }
css-loader 的 options 里必须有 modules: { mode: 'local', getLocalIdent: getCSSModuleLocalIdent }，不能只写 modules: true
importLoaders: 2 是底线值——因为 @import 语句需要 less-loader 和 css-loader 共同解析

less-loader@10+ 为什么报 this.getOptions is not a function？

这是 Webpack 4（CRA v4/v5 默认）和 less-loader@10+ 不兼容的静默崩溃。错误发生时，Webpack 4 的 loader API 不识别新版本的 getOptions 方法，导致整个 less-loader 初始化失败，进而让 css-loader 拿不到有效样式内容，最终 styles 对象为空。

CRA v4 项目必须锁定 [email protected]：npm uninstall less-loader && npm install [email protected] --save-dev
less 本身可用最新版（如 [email protected]），不影响 Ant Design 等依赖
如果误装了 less-loader@10+，即使 lessOptions 写对了，也会完全失效——没有报错提示，只有空对象

全局变量怎么注入到所有 .module.less 文件？

不能靠 @import 手动引入每个文件，那样违背模块化初衷。正确方式是通过 less-loader 的 additionalData 选项（v7.3.0 支持）或 modifyVars 预设变量。后者更轻量，适合主题色、间距等常量。

用 modifyVars 注入基础变量：modifyVars: { '@primary-color': '#1DA57A', '@border-radius-base': '4px' }
若需注入完整变量文件（如 variables.less），改用 additionalData（注意路径必须是绝对路径）：additionalData: `@import "${path.resolve(__dirname, '../src/variables.less')}";`
避免在 additionalData 中写 @import '~antd/lib/style/themes/default.less' 这类别名路径——Webpack 别名在 less-loader 层不生效，会报 File not found