vue-test-utils搭配jest运行单元测试时报无法定位模块配置错误

问题复现特征 #

• 共4个Vue组件接入单元测试，其中3个组件测试用例全部运行正常
• 仅EditorContextPanel组件测试套件触发加载异常，终端抛出Configuration error
• 报错提示无法定位模块@/lib-components/assets/svg/Icons，错误溯源指向src/lib-components/editor/BlockTools/TableBlock.ts第2行的Icons导入语句，判定为moduleNameMapper中@路径映射解析失败
• 已在package.json中完成Jest基础配置：包含@路径映射规则、文件转译规则、静态资源mock规则，执行测试命令为vue-cli-service test:unit --no-cache

按优先级排查修复 #

1. 检查moduleNameMapper规则匹配范围与顺序
   多数用例正常仅单链路解析失败，首先排除基础配置失效问题，优先检查规则漏洞：
   • 常见错误1：@路径映射的目标地址写死后缀，比如配置为<rootDir>/src/$1.vue，导致.ts/.tsx文件中的@导入无法匹配
   • 常见错误2：静态资源mock规则放在@映射规则前面，正则提前拦截了正常的业务模块导入请求
     正确配置参考：

   "moduleNameMapper": {
     "^@/(.*)$": "<rootDir>/src/$1",
     "\\.(svg|png|jpg|jpeg|css|less|scss)$": "<rootDir>/tests/__mocks__/fileMock.js"
   }
   

2. 校验目标模块文件与导入逻辑
   定位到src/lib-components/assets/svg/Icons文件逐一核对：
   • 确认文件实际后缀与导入语句匹配，同时检查Jest的moduleFileExtensions配置是否包含所有业务文件后缀，常规配置为["vue", "ts", "tsx", "js", "jsx", "json"]，按匹配优先级从高到低排列
   • 排查是否存在循环导入：如果Icons文件反向依赖了TableBlock或者EditorContextPanel下的模块，会导致Jest模块加载链路中断，抛出伪装成路径映射失败的错误
3. 核对转译规则排除范围
   检查transformIgnorePatterns配置的正则是否误匹配到src下的业务目录，比如错误写了/lib/规则导致lib-components目录下的文件被跳过转译，Jest无法识别未转译文件内的@路径导入。该配置常规场景下仅需排除node_modules目录即可：

   "transformIgnorePatterns": ["/node_modules/"]
   

4. 校验路径大小写完全匹配
   macOS、Windows系统本地文件路径默认不区分大小写，但Jest模块解析严格遵循大小写敏感规则。如果文件实际名称为icons.ts（小写开头），但导入语句写为@/lib-components/assets/svg/Icons（大写开头），未触发该导入链路的测试用例会正常运行，只有加载到TableBlock模块时才会抛出找不到模块的错误，该问题误判率极高。

快速定位技巧 #

• 临时将TableBlock.ts中的Icons导入改为相对路径，重跑测试如果报错直接消失，即可确定为moduleNameMapper规则漏洞，调整正则匹配范围和顺序即可修复
• 执行测试时追加--verbose参数，终端会打印Jest解析每个模块的完整磁盘路径，将解析结果和实际文件路径直接对比，可快速定位路径拼接错误

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