将遗留LESS文件转为CSS Modules时遭遇构建错误求助

问题描述 #

我正尝试将遗留代码库中的LESS文件转换为CSS Modules，已更新webpack的css-loader配置如下：

{
  loader: 'css-loader',
  options: {
    modules: {
      // for now, only enable CSS modules for LESS files with ".module."
      auto: /\.module\.\w+$/i, 
      localIdentName: '[sha1:hash:hex:6]',
    },
  },
}

随后将某LESS文件从something.less重命名为something.module.less。代码库类名均为短横线命名（kebab cased），虽CSS Modules偏好驼峰式（camelCase），但可通过styles['some-class-name']访问。

客户端应用无法构建，报错提示.user-profile-wrapper { // styles here }行存在意外令牌。尝试将类名改为.wrapper { // styles here }后，客户端构建成功，但Node服务器在该类名前的点处报unexpected token '.'错误，错误栈如下：

/path/to/app/styles/home/something.module.less:1
.wrapper {
^

SyntaxError: Unexpected token '.'
    at wrapSafe (node:internal/modules/cjs/loader:1378:20)
    at Module._compile (node:internal/modules/cjs/loader:1428:41)
    at Module._extensions..js (node:internal/modules/cjs/loader:1548:10)
    at Object.newLoader [as .js] (/path/to/app/node_modules/pirates/lib/index.js:121:7)
    at Module.load (node:internal/modules/cjs/loader:1288:32)
    at Function.Module._load (node:internal/modules/cjs/loader:1104:12)
    at Module.require (node:internal/modules/cjs/loader:1311:19)
    at require (node:internal/modules/helpers:179:18)
    at Object.<anonymous> (/path/to/app/components/home/MyComponent.tsx:6:1)
    at Module._compile (node:internal/modules/cjs/loader:1469:14)

问题原因 #

1. Node服务器未通过webpack loader处理.module.less文件——Node本身无法识别LESS/CSS语法，会把.less文件当成普通JS模块解析，遇到CSS的.选择器时自然抛出语法错误。客户端构建成功是因为webpack通过css-loader/less-loader完成了转译，但Node端（比如SSR场景）的模块解析流程未配置对应loader，直接执行了原始LESS代码。
2. 最初客户端报错.user-profile-wrapper，是因为组件中直接使用了字符串类名（如className="user-profile-wrapper"），而非通过CSS Modules导出的styles对象访问（正确写法应为className={styles['user-profile-wrapper']}）。

解决方案 #

1. 让Node端正确处理LESS文件 #

如果是SSR项目，需要为Node端单独配置webpack构建，确保less-loader、css-loader（开启modules）被包含在loader链中，将LESS文件转译为Node可识别的JS模块（导出styles对象）；也可以使用babel-plugin-css-modules-transform这类工具，让Babel在转译TSX/JSX时处理CSS Modules。

2. 修正组件中类名的引用方式 #

所有.module.less中的类名必须通过导入的styles对象访问，示例：

import styles from './something.module.less';
// 正确写法
<div className={styles['user-profile-wrapper']}></div>
// 错误写法（会导致客户端构建报错）
<div className="user-profile-wrapper"></div>

3. 补全webpack配置的loader链 #

确保webpack配置中包含less-loader，且loader顺序为less-loader先转译LESS为CSS，再由css-loader处理CSS Modules：

module: {
  rules: [
    {
      test: /\.module\.less$/,
      use: [
        'style-loader', // 生产环境可替换为mini-css-extract-plugin
        {
          loader: 'css-loader',
          options: {
            modules: {
              auto: /\.module\.\w+$/i,
              localIdentName: '[sha1:hash:hex:6]',
            },
          },
        },
        'less-loader',
      ],
    },
    // 保留非module的LESS文件配置（如有需要）
    {
      test: /\.less$/,
      exclude: /\.module\.less$/,
      use: ['style-loader', 'css-loader', 'less-loader'],
    },
  ],
}

内容的提问来源于stack exchange，提问作者noblerare