Next.js运行Jest测试报Cannot find module模块解析错误

Jest 执行测试时默认不会读取 tsconfig.json 中定义的路径别名规则，业务代码里使用的 @components/Layout 这类带@前缀的导入路径，Jest 无法映射到本地真实文件目录，因此抛出模块找不到的错误，报错指向404页面的导入语句只是因为测试流程首次解析到这个别名路径的位置在该文件首行。

• 首先确认已安装ts-jest依赖，未安装的话先在项目根目录执行安装命令：

npm install --save-dev ts-jest

• 打开项目根目录的 jest.config.js 文件，修改配置让Jest直接复用tsconfig里的路径映射规则，不需要重复维护别名配置：

const nextJest = require('next/jest')
// 引入ts-jest提供的路径转换方法
const { pathsToModuleNameMapper } = require('ts-jest')
// 读取本地tsconfig配置
const tsconfig = require('./tsconfig.json')

const createJestConfig = nextJest({
  dir: './',
})

const jestConfig = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  // *核心配置*：自动映射tsconfig里的所有路径别名
  moduleNameMapper: pathsToModuleNameMapper(tsconfig.compilerOptions.paths, {
    prefix: '<rootDir>/'
  }),
}

module.exports = createJestConfig(jestConfig)

• 检查 tsconfig.json 的配置，确保已经设置了根目录baseUrl，路径别名格式符合要求：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["components/*"]
      // 你原来配置的其他别名保持不变即可
    }
  }
}

• 清空Jest历史缓存后重新执行测试命令，避免旧缓存影响配置生效：

npx jest --clearCache
# 之后再执行你原来的测试命令即可，比如npm run test

• 不建议手动在moduleNameMapper里硬编码单个别名规则，后续修改tsconfig路径时容易出现两边配置不一致的问题，用自动映射的方式维护成本最低
• baseUrl必须配置为当前根目录"."，否则路径前缀拼接错误依然会报模块找不到
• 如果你的项目是monorepo结构，注意require('./tsconfig.json')的路径要指向你当前Next.js应用对应的tsconfig文件，不要读到根目录的公共配置

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