Jest使用路径映射时提示找不到模块该如何解决？

云上老周

2026-8-30

问题根因

测试运行时（Jest、Vitest等单测工具）默认不会读取项目里构建工具（Webpack、Vite、TSC）配置的路径映射规则，模块解析仅遵循Node.js默认的查找逻辑：先找node_modules依赖，再按相对路径匹配文件，完全识别不了@pages/这类自定义别名，因此抛出模块找不到的报错。

修复方案

根据项目使用的测试框架选对应配置即可：

基于Jest的项目

在Jest配置文件（jest.config.js/jest.config.ts）中添加moduleNameMapper字段，手动声明别名和实际物理路径的映射关系：

module.exports = {
  // 其余原有Jest配置
  moduleNameMapper: {
    "^@pages/(.*)$": "<rootDir>/src/pages/$1",
    // 其余自定义别名按相同规则追加即可，比如全局@别名
    "^@/(.*)$": "<rootDir>/src/$1"
  },
  // 确认tsx/ts后缀在解析列表中
  moduleFileExtensions: ["ts", "tsx", "js", "jsx"]
}

如果路径别名已经统一配置在tsconfig.json的compilerOptions.paths中，可以直接用ts-jest提供的工具方法自动生成映射规则，不用重复手写：

const { pathsToModuleNameMapper } = require("ts-jest");
const tsConfig = require("./tsconfig.json");

module.exports = {
  preset: "ts-jest",
  moduleNameMapper: pathsToModuleNameMapper(tsConfig.compilerOptions.paths, {
    prefix: "<rootDir>/"
  })
}

基于Vitest的项目
Vitest默认会自动读取Vite配置中的resolve.alias规则，如果未生效直接在vite.config.ts中显式声明别名即可：

import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@pages": path.resolve(__dirname, "src/pages"),
      "@": path.resolve(__dirname, "src")
    }
  },
  test: {
    // 其余测试配置
  }
});