AWS CDK v2 Synth无法找到NPM链接peer依赖模块解决方案

我有一个AWS CDK v2项目，在package.json中通过如下配置引入本地npm包时，可以正常执行cdk synth命令：

"@my/constructs": "file:../my/dist/packages/constructs"

这个包存放在独立的Nx monorepo仓库中，同仓库下还有另一个包@my/coolthing。当我在@my/constructs包内引入@my/coolthing时，CDK执行synth抛出错误：

Cannot find module '@my/coolthing'

@my/constructs的package.json已经在peerDependencies字段正确声明了@my/coolthing依赖，配置如下：

"peerDependencies": {
    "@my/coolthing": "1.0.0"
}

已尝试以下操作但均未解决问题：

• 手动将@my/coolthing目录复制到CDK项目的node_modules文件夹
• 将@my/coolthing发布到NPM官方源后，在CDK项目中执行npm install完成安装

这个问题的根因是CDK synth阶段有独立的模块解析和依赖校验逻辑，和普通Node.js项目的解析规则不一样：它只会识别当前CDK项目package.json中显式声明、且符合peer依赖版本要求的包，不会顺着file:协议引用的本地包，自动追溯同monorepo下的其他关联内部包。你之前两种尝试失效的原因也很明确：

• 手动复制到node_modules的包没有进入项目的依赖锁文件，CDK做依赖扫描时会直接忽略这类未登记的包
• 公网发布后安装仍失败，基本是Nx构建产出的@my/constructs包中，peerDependencies声明的版本和你实际发布的@my/coolthing版本不匹配，CDK的peer依赖校验不通过，就会判定这个包不存在。

按下面步骤操作即可解决：

1. 在CDK项目的package.json中，把两个本地包都用file:协议显式声明为依赖，路径统一指向Nx构建后的dist产物目录，不要指向源码目录：

   "dependencies": {
     "@my/constructs": "file:../my/dist/packages/constructs",
     "@my/coolthing": "file:../my/dist/packages/coolthing",
     "aws-cdk-lib": "^2.0.0",
     "constructs": "^10.0.0"
   }
   

2. 删除CDK项目下的node_modules目录和package-lock.json文件，重新执行npm install。安装完成后先执行npm ls @my/coolthing校验，确认命令输出中没有依赖版本冲突、@my/coolthing存在于顶层依赖树中，同时确认node_modules/@my/constructs下没有嵌套安装重复的@my/coolthing包。
3. 校验Nx构建产出的@my/constructs包内的package.json文件，确认dist目录下的最终产物文件中，确实保留了@my/coolthing的peerDependencies声明——部分Nx构建配置会默认裁剪内部monorepo包的依赖声明，会直接导致CDK解析依赖时找不到关联项。
4. 如果上述操作完成后仍有报错，可以换用npm link的方式做本地联调，绕开file协议的路径解析问题，注意两个包都要做link，不要只link@my/constructs：

   # 进入Nx构建后的两个包目录，分别注册到全局link
   cd ../my/dist/packages/coolthing && npm link
   cd ../my/dist/packages/constructs && npm link
   
   # 回到CDK项目目录，关联两个本地包
   cd ../../../your-cdk-project-path
   npm link @my/coolthing @my/constructs
   

5. 最后重新执行cdk synth即可正常运行。

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