pnpm workspace构建部署时找不到@sendgrid/mail模块问题

核心原因 #

构建工具编译shared模块时，会将依赖路径解析为相对于最终输出目录的形式。部署时Node.js会从customer服务根目录开始查找node_modules，不会自动回溯到shared自身的node_modules目录，这就是报错的根源。

可行解决方法 #

1. 声明peer依赖并在消费方安装 #

在shared的package.json中添加peer依赖声明：

"peerDependencies": {
  "@sendgrid/mail": "^7.6.0"
}

然后在customer服务中安装该依赖：

pnpm add @sendgrid/mail@^7.6.0 --filter customer

这是符合pnpm workspace规范的做法，确保依赖存在于消费方的node_modules中，避免嵌套查找问题。

2. 配置构建工具保留符号链接 #

如果使用TypeScript编译，在shared的tsconfig.json中启用preserveSymlinks：

{
  "compilerOptions": {
    "preserveSymlinks": true,
    "moduleResolution": "NodeNext"
  }
}

该配置会让Node.js运行时遵循符号链接的原始路径，从而找到shared自身node_modules中的依赖。注意部署时要保留shared模块的符号链接结构，或者将shared的node_modules同步到部署目录。

3. 将shared打包为包含依赖的独立模块 #

用rollup、webpack等工具把shared打包成包含所有依赖的CommonJS/UMD模块，这样@sendgrid/mail会被打包进shared的输出文件，无需外部查找。但这种方式会增大包体积，适合依赖较少的共享模块。

为什么不推荐强制嵌套查找 #

pnpm的核心设计是扁平化依赖、避免冗余，强制让Node.js查找嵌套的node_modules会破坏其依赖管理逻辑，容易引发版本冲突和部署复杂度上升，上述规范内的方法更稳定可靠。

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