Next.js项目Jest无法解析CSS模块的问题排查与解决

问题原因 #

Jest默认不具备解析CSS模块的能力，当测试用例中导入Home.module.css时，ts-jest会将其当作JavaScript文件解析，而CSS语法（比如.container）不符合JavaScript规范，因此抛出SyntaxError: Unexpected token '.'错误。

解决步骤 #

1. 安装依赖 #

安装identity-obj-proxy，它会将CSS模块导出为一个键值对与类名一致的对象，满足测试场景下对CSS模块的导入需求：

npm install --save-dev identity-obj-proxy

2. 配置Jest模块映射 #

修改jest.config.js，添加moduleNameMapper规则，指定CSS文件的处理方式：

/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'jsdom',
  moduleNameMapper: {
    // 处理CSS/SCSS/SASS模块
    '\\.(css|scss|sass)$': 'identity-obj-proxy',
    // 可选：处理图片等静态资源（如果项目中有导入）
    '\\.(png|jpg|jpeg|gif|svg)$': '<rootDir>/__mocks__/fileMock.js',
  },
};

3. （可选）处理静态资源Mock（如图片） #

如果项目中存在图片等静态资源导入，在项目根目录创建__mocks__/fileMock.js文件，内容如下：

module.exports = 'test-file-stub';

4. 验证修复 #

重新运行测试命令：

npm test

此时测试应该可以正常执行，不再出现CSS解析的语法错误。

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