根本原因是Jest不自动读取Webpack/Vite或tsconfig/jsconfig的paths别名，需手动配置moduleNameMapper映射，如"^@/(.*)$": "/src/$1"，并同步检查jsconfig.json/tsconfig.json中baseUrl和paths配置、moduleFileExtensions扩展名及roots等设置。
JS 项目引入 Jest 后，出现 Cannot find module '@/utils' 或类似路径别名报错，根本原因不是 Jest 本身不支持别名，而是它默认不读取 Webpack/Vite 的别名配置，也不自动识别 tsconfig.json 或 jsconfig.json 中的 paths 映射。必须手动告诉 Jest 如何解析 @/ 这类路径。
配置 moduleNameMapper 映射别名
Jest 通过 moduleNameMapper 选项实现路径别名解析，本质是正则替换导入路径。需在 jest.config.js 中添加：
- 确保
src目录路径准确（推荐用path.resolve(__dirname, 'src')） - 正则要能匹配所有
@/xxx形式，且捕获后续路径用于拼接 - 使用
<rootdir></rootdir>安全引用项目根目录，避免硬编码
示例配置：
"moduleNameMapper": {
"^@/(.*)$": "<rootDir>/src/$1"
}
同步检查 jsconfig.json 或 tsconfig.json
VSCode 和 TypeScript 编译器依赖该文件识别别名，但 Jest 不会自动读取它。不过如果缺失该文件，编辑器里也会标红，容易误判为 Jest 问题。请确认根目录存在且内容正确：
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
注意：jsconfig.json 适用于纯 JS 项目，tsconfig.json 适用于 TS 项目；文件必须放在你打开 VSCode 工作区的根目录下。
处理文件后缀和扩展名
如果导入时省略了 .js（如 import utils from '@/utils'），Jest 默认只尝试 .js、.json，不包含 .ts 或无后缀文件。需显式配置 moduleFileExtensions：
"moduleFileExtensions": ["js", "jsx", "ts", "tsx", "json", "node"]
若项目中大量使用无后缀导入，建议统一加 .js 后缀，或确保 resolve.extensions 在打包工具和 Jest 中保持一致。
验证是否被其他配置覆盖
常见干扰项包括：
-
transformIgnorePatterns错误排除了src目录，导致别名路径未被正确处理 -
roots配置范围过窄（如只设['src']），导致 Jest 无法定位根目录下的配置文件 - 使用了 ESM 模式但未启用
experimentalVmModules，此时moduleNameMapper可能不生效（尤其 Node ≥18）
建议 roots 设为 ['<rootdir>']</rootdir>，并检查 transformIgnorePatterns 是否误含 /src/。
