Next.js + Jest 非TypeScript环境下moduleNameMapper配置失效问题

1. 确认jsconfig.json配置正确性 #

先确保你的jsconfig.json配置和项目结构匹配，示例如下：
如果代码直接放在项目根目录：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["*"]
    }
  }
}

如果代码集中在src目录下：

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

2. 正确配置jest.config.js #

方案一：使用next/jest预设（推荐，适配NextJS） #

先安装依赖（未安装的话）：npm install --save-dev next/jest，然后配置：

const nextJest = require('next/jest')

const createJestConfig = nextJest({
  dir: './', // 项目根目录路径
})

const customJestConfig = {
  testEnvironment: 'jsdom',
  moduleNameMapper: {
    // 严格匹配@/开头的导入，映射到对应路径
    '^@/(.*)$': '<rootDir>/$1',
    // 若代码在src目录，改为 '<rootDir>/src/$1'
  },
}

module.exports = createJestConfig(customJestConfig)

方案二：手动配置Jest #

如果不使用next/jest，手动配置模块路径和转换规则：

module.exports = {
  testEnvironment: 'jsdom',
  // 映射@/xxx到项目对应文件路径
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/$1',
    // src目录结构则改为 '<rootDir>/src/$1'
  },
  // 对应jsconfig的baseUrl，告知Jest模块查找根路径
  modulePaths: ['<rootDir>/'],
  // 处理JS/JSX文件的转换逻辑
  transform: {
    '^.+\\.(js|jsx)$': 'babel-jest',
  },
}

3. 常见问题排查 #

• 正则匹配错误：确保moduleNameMapper里的正则为^@/(.*)$，^和$用于精确匹配开头和结尾，避免部分匹配导致失效。
• 路径不匹配：moduleNameMapper的映射路径必须和jsconfig.json的paths完全对应，比如jsconfig中@/*指向src/*，jest里就要映射到<rootDir>/src/$1。
• 缓存残留：执行jest --clearCache清除Jest缓存，再重新运行测试，避免旧配置干扰。
• 文件路径错误：确认报错中的模块（比如@/hooks/fetch）对应的实际文件存在，无大小写或拼写错误。

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