TypeScript+Jest项目中*.test.ts测试文件无法使用路径别名问题

两个配置错误共同导致问题：

• Jest的moduleNameMapper规则写法错误：原配置的正则键'/^@(.*)$'存在两处问题：一是字符串外层多写了正则边界符/，二是未匹配@后的路径斜杠，导致规则完全无法命中@/xxx格式的导入路径，Jest运行时无法解析别名。
• tsconfig.json的类型检查范围配置错误：include仅覆盖了src目录下的TS文件，未纳入测试文件，同时exclude规则主动排除了所有*.spec.ts文件，TS语言服务无法对测试文件执行路径别名的类型解析，才会抛出找不到模块类型声明的错误。

1. 修正Jest别名匹配规则 #

修改jest.config.ts中的moduleNameMapper配置，修正正则写法：

moduleNameMapper: {
  '^@/(.*)$': '<rootDir>/src/$1',
},

说明：字符串形式的正则匹配规则不需要额外包裹/边界符，补全@/的斜杠匹配后，所有以@/开头的导入都会被正确映射到项目src目录对应路径。

2. 调整TS配置的文件覆盖范围 #

修改tsconfig.json的include和exclude规则，将测试文件纳入类型检查范围，移除对测试文件的误排除：

{
  "compilerOptions": {
    // 保留原有其他编译配置不变
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "**/*.test.ts",
    "**/*.spec.ts",
    "tests/**/*.ts"
  ],
  "exclude": ["node_modules", "tests/coverage"]
}

如果测试文件统一存放在固定目录（如根目录tests文件夹），可根据实际目录结构精简include规则，确保所有需要类型检查的测试文件被覆盖即可。

3. （可选）消除别名配置重复维护 #

如果不想在Jest和TS配置中重复维护别名规则，可直接复用tsconfig中的paths配置，避免后续两边配置不一致引发问题：

1. 安装依赖：

npm install -D ts-jest tsconfig-paths

2. 修改jest.config.ts，替换原有硬编码的moduleNameMapper：

import type { Config } from '@jest/types';
import { pathsToModuleNameMapper } from 'ts-jest';
import tsconfig from './tsconfig.json';

const config: Config.InitialOptions = {
  verbose: true,
  preset: 'ts-jest',
  clearMocks: true,
  collectCoverage: true,
  coverageDirectory: 'tests/coverage',
  collectCoverageFrom: ['<rootDir>/src/**/*.ts?'],
  coverageProvider: 'v8',
  moduleFileExtensions: ['js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'json', 'node'],
  rootDir: '.',
  // 直接读取tsconfig的paths配置生成映射规则
  moduleNameMapper: pathsToModuleNameMapper(tsconfig.compilerOptions.paths, {
    prefix: '<rootDir>/',
  }),
  modulePathIgnorePatterns: ['tests/coverage'],
  testMatch: ['**/tests/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
  testEnvironment: 'node',
};

export default config;

3. 在tsconfig.json的compilerOptions中新增配置，让ts-node执行jest配置时能识别别名：

"ts-node": {
  "require": ["tsconfig-paths/register"]
}

验证修复 #

重新执行测试命令即可正常运行：

jest --config ./jest.config.ts --coverage

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