Umi4 项目中配置 CSS Modules 小驼峰命名的正确方式

在使用 Umi4 框架开发 React 项目时，很多开发者会遇到需要将 CSS 类名转换为小驼峰格式的需求。这种需求源于团队规范或项目约定，希望在使用 CSS Modules 时能够保持 JavaScript 的命名一致性。

问题背景

在 Umi4 项目中，默认情况下 CSS Modules 会将类名原样导出。例如，一个名为 .bar-foo 的 CSS 类，在 JavaScript 中需要通过 styles['bar-foo'] 的方式引用。而开发者更希望使用小驼峰形式 styles.barFoo 来引用这个类名。

错误配置方式

很多开发者会尝试在 config.ts 中直接配置 cssLoader 选项：

export default {
  cssLoader: {
    modules: {
      exportLocalsConvention: 'camelCase'
    }
  }
}

这种配置会导致 Umi4 报错，提示 cssLoader.modules 不是一个有效的配置项。这是因为 Umi4 的配置结构有其特定的设计，不能直接照搬 webpack 的配置方式。

正确配置方法

在 Umi4 中，正确的配置方式应该是：

export default {
  cssLoader: {
    modules: {
      localsConvention: 'camelCase'
    }
  }
}

关键点在于使用 localsConvention 而不是 exportLocalsConvention。这个配置项控制着 CSS Modules 如何转换类名格式。

配置选项详解

localsConvention 支持以下几种模式：

1. 'asIs'（默认）：保持类名原样，不做转换
2. 'camelCase'：将类名转换为小驼峰格式
3. 'camelCaseOnly'：只使用小驼峰格式，不保留原始类名
4. 'dashes'：同时保留短横线格式和小驼峰格式
5. 'dashesOnly'：只保留短横线格式

实际应用示例

配置完成后，开发者可以这样使用 CSS Modules：

import styles from './index.less'; // .bar-foo { font-size: 16px; }

export default () => <div className={styles.barFoo}>Hello</div>;

编译后的 HTML 会正确保留原始的类名格式：

<div class="bar-foo___{hash}">Hello</div>

注意事项

1. 确保项目中使用的是最新版本的 Umi4，不同版本可能有不同的配置方式
2. 如果配置后没有生效，可以尝试清理构建缓存重新启动项目
3. 在 TypeScript 项目中，可能需要更新类型定义文件以反映类名的变化

通过正确配置 cssLoader.modules.localsConvention 选项，开发者可以在 Umi4 项目中轻松实现 CSS 类名的小驼峰转换，提高代码的一致性和可读性。