切换至Yarn后部分成员遇到TypeScript依赖解析失败问题

这种Yarn切换后TS依赖解析的问题我之前在团队迁移时也碰到过，结合你的场景——大型Maven多模块UI项目，多数成员/CI正常，仅两位成员出现moment这类常见依赖无法解析、Jest/Webpack构建失败的情况，大概率是下面几个常见原因导致的，给你整理了排查和解决的步骤：

1. Yarn版本不一致 #

不同Yarn版本的依赖安装逻辑、锁文件格式差异很大（比如Yarn 1.x和Yarn 2+的node_modules结构完全不同），如果这两位成员的Yarn版本和团队/CI不一致，很容易出现依赖路径不匹配的问题。

• 解决步骤：
  • 先确认团队统一使用的Yarn版本（比如查看CI配置或项目根目录的yarn.lock头部的版本信息）
  • 让这两位成员卸载当前Yarn，安装对应版本：可以用npm install -g yarn@x.x.x，或者用volta这类工具统一管理版本
  • 删除项目内的node_modules、yarn.lock文件，重新执行yarn install

2. 本地缓存污染 #

Yarn的本地缓存可能损坏，或者之前npm的缓存残留，导致依赖安装不完整、路径异常。

• 解决步骤：
  • 执行yarn cache clean清理Yarn全局缓存
  • 删除UI子项目及Maven根目录下的node_modules、yarn.lock
  • 进入UI子项目目录，重新执行yarn install，确保完全拉取干净的依赖

3. TypeScript配置路径问题 #

转用Yarn后，依赖的实际路径可能和npm时期有细微差异，而TS的tsconfig.json配置没跟上，导致解析失败。

• 解决步骤：
  • 打开UI子项目的tsconfig.json，检查baseUrl和paths配置：确保baseUrl指向项目根目录，paths里没有错误的映射规则
  • 可以临时添加明确的依赖映射测试：比如在paths中加入"moment": ["node_modules/moment"]，看TS是否能正常解析
  • 确认typeRoots选项包含node_modules/@types，确保类型定义文件能被正确识别

4. Maven多模块的路径干扰 #

因为是Maven多模块项目，UI子项目的依赖安装上下文可能出错（比如误在Maven根目录执行yarn install，而非UI子项目目录），导致node_modules位置不符合TS/Webpack/Jest的预期。

• 解决步骤：
  • 确认这两位成员是在UI子项目的package.json所在目录执行的yarn install
  • 检查Webpack配置的resolve.modules选项，确保包含path.resolve(__dirname, 'node_modules')（指向UI子项目自己的依赖目录）
  • 检查Jest配置的modulePaths或moduleDirectories，同样确保指向正确的node_modules路径

5. 类型定义缺失或不兼容 #

虽然文件系统里有moment包，但对应的@types/moment可能没被正确安装，或者版本和moment不兼容，导致TS无法解析类型。

• 解决步骤：
  • 执行yarn add @types/moment --dev，明确安装类型定义
  • 检查package.json中moment和@types/moment的版本，确保两者兼容（比如moment@2.29.x对应@types/moment@2.29.x）

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