Jest测试引入npm共享库源码报意外token的配置解决方案

Jest默认的转译逻辑会全局跳过node_modules目录下的所有文件，当前App项目通过@xxx/library/src/entities/address路径，直接引入了共享library项目未经过编译的TypeScript源码。这类文件带有TS专有语法（类型标注、接口定义等），未经过转译就被Jest加载，自然会触发「遇到意外token」的报错。

之前多轮配置调整不生效的高频踩坑点：

• 配置逻辑完全反向：将需要转译的共享library路径错误加入transformIgnorePatterns的忽略列表，等于主动告知Jest不对这类文件做转译处理，直接跳过源码加载流程
• 转译规则覆盖不全：ts-jest的匹配规则仅覆盖App项目内部的TS/JS文件，没有覆盖到node_modules下共享library的src路径
• 引用路径不规范：直接引入未编译的源码路径，而非library打包输出的可运行JS产物

方案1：保留源码直引模式下的Jest配置修正 #

1. 调整transformIgnorePatterns的匹配逻辑：将默认忽略规则改为排除需要转译的共享library路径，明确告知Jest不要忽略该目录下的文件，参考配置：

   transformIgnorePatterns: [
     "/node_modules/(?!(@xxx/library/.*))/"
   ]
   

2. 补全ts-jest转译规则的匹配范围，确保覆盖共享library目录下的TS/JS文件，同时配置路径解析规则避免TS类型识别报错：

   transform: {
     "^.+\\.(ts|tsx|js|jsx)$": ["ts-jest", {
       tsconfig: {
         paths: {
           "@xxx/library/*": ["node_modules/@xxx/library/src/*"]
         }
       }
     }]
   }
   

方案2：更稳定的长期项目结构适配 #

放弃直接引入共享library未编译源码的写法，优先引用library的编译产物：

• 调整共享library的打包流程，完成TS到纯JS的转译，同步生成对应的类型声明文件
• 修改App项目内的引用路径，将原本指向src的引入语句，替换为指向编译后产物路径的写法：
  原引入：import { mockAddress } from '@xxx/library/src/entities/address';
  调整后：import { mockAddress } from '@xxx/library/dist/entities/address';
• 这种模式下不需要额外调整Jest的转译规则，因为引入的文件本身就是可被Node直接识别的纯JS，不会触发语法解析报错

• transformIgnorePatterns的核心作用是标记需要被Jest跳过转译的路径，而非标记需要转译的路径，逻辑写反是这类配置调整不生效的最常见原因
• 不要移除全局的node_modules忽略规则，否则Jest会尝试转译所有第三方依赖，大幅拉长测试启动耗时，还可能引入无意义的第三方依赖语法兼容问题
• 本地link调试共享library时，需要确保Jest能正确识别软链路径，避免路径解析错位导致的配置不生效

内容的提问来源于stack exchange，提问作者Léo Coco