React+TS+Webpack环境下CSS Modules导入后类名undefined求助

我正在使用React（18.2.0）、TypeScript（4.8.4）和Webpack（5.75.0）开发应用，尝试通过CSS Modules添加样式。最初无论如何配置Webpack loader，都会出现模块解析失败的错误，提示缺少合适的loader处理CSS文件。后来发现需重启webpack serve才能让配置生效，此时Webpack可成功编译，但新问题出现：在.ts文件中导入的CSS Modules类名始终返回undefined，导致样式无法应用。奇怪的是，语言服务器tsserver能自动补全.css文件中定义的类名，但console.log输出styles中的类名时却显示undefined。我已确认混淆后的CSS类名存在于最终渲染页面的内联样式中，也尝试过手动声明.d.ts文件、重命名CSS文件等方法，但问题仍未解决。

相关代码片段 #

样式导入代码 #

import * as styles from './ResultCount.module.css'

export const ResultCount = () => {
  const orders = useSelector((state: ReducedState) => state.all.orders)
  console.log('result count style name', styles.results) // always undefined

  return <p className={styles.results}>

src/Globals.d.ts #

declare module '*.module.css'

Webpack配置片段 #

module: {
  rules: [
    {
      test: /\.tsx?$/,
      loader: 'ts-loader',
      options: {
        transpileOnly: true
      },
      exclude: /dist/
    },
    {
      test: /\.css$/,
      use: [
        "style-loader",
        {
          loader: "css-loader",
          options: {
            modules: true,
            importLoaders: 1,
            localIdentName: "[name]_[local]_[hash:base64]",
            sourceMap: true,
            minimize: true
          }
        }
      ]
    },
    // 注释的其他loader配置
  ]
},

可能的原因及对应修复步骤 #

1. CSS Modules类型声明不完整 #

当前的Globals.d.ts仅声明了模块，但未定义导出结构，导致TypeScript无法正确推断类名映射关系——虽然tsserver能触发补全，但实际编译后导出逻辑异常。

修复：更新类型声明为完整结构：

declare module '*.module.css' {
  const classes: Record<string, string>;
  export = classes;
}

修改后重启IDE或tsserver，确保类型生效。

2. Webpack规则匹配范围错误 #

当前规则对所有.css文件启用CSS Modules，若项目同时存在全局CSS，可能引发解析冲突；另外importLoaders:1属于冗余配置（未配置前置loader如postcss-loader），可能干扰解析逻辑。

修复：调整规则仅匹配模块化CSS文件：

{
  test: /\.module\.css$/, // 仅针对模块化CSS文件生效
  use: [
    "style-loader",
    {
      loader: "css-loader",
      options: {
        modules: {
          localIdentName: "[name]_[local]_[hash:base64]",
        },
        sourceMap: true,
        minimize: true
      }
    }
  ]
},
// 新增全局CSS规则（按需添加）
{
  test: /\.css$/,
  exclude: /\.module\.css$/, // 排除模块化CSS
  use: ["style-loader", "css-loader"]
}

3. ts-loader的transpileOnly模式限制 #

transpileOnly: true会跳过TypeScript类型检查，仅做代码转译，可能导致CSS Modules的类型导出未被正确处理，出现编译通过但运行时导出异常的情况。

修复：暂时关闭该模式验证：

{
  test: /\.tsx?$/,
  loader: 'ts-loader',
  options: {
    // transpileOnly: true, 注释该行
    happyPackMode: true // 可选：配合happypack提升编译性能
  },
  exclude: /dist/
}

4. CSS文件语法或类名问题 #

确认ResultCount.module.css中存在.results类，且无语法错误（如未闭合的括号、无效属性等）——CSS语法错误会导致css-loader无法正确解析并导出类名。

5. Webpack缓存残留 #

重启webpack serve后可能仍有旧缓存，导致解析异常。

修复：删除缓存目录或启动时禁用缓存：

# 删除缓存目录
rm -rf node_modules/.cache
# 或启动时添加参数
webpack serve --no-cache

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