AWS CDK执行synth时无法识别项目中的自定义.d.ts文件

问题场景 #

TypeScript CDK项目中，基础设施与运行时代码同目录，运行时代码依赖无类型定义的小众JS库，已创建自定义.d.ts声明文件，tsc构建正常，但执行cdk synth时提示Could not find a declaration file for module 'xyz'，移除cdk.json中exclude的**/*.d.ts无效。

解决方案 #

1. 强制ts-node加载项目tsconfig #

CDK默认通过ts-node执行入口文件，可能未正确读取你的tsconfig.json配置。修改cdk.json中的app字段，添加--project tsconfig.json参数：

{
  "app": "npx ts-node --project tsconfig.json --prefer-ts-exts bin/LeopardGeotabApp.ts",
  // 其他配置保持不变
}

2. 检查自定义声明文件的命名与位置 #

• 确保声明文件名与模块名匹配：如果依赖库是xyz，声明文件需命名为xyz.d.ts
• 若声明文件放在types目录下（对应tsconfig的typeRoots配置），需保证目录结构为types/xyz/index.d.ts或直接types/xyz.d.ts
• 若声明文件与运行时代码同目录，确认tsconfig.json的include已覆盖该目录（你的配置中lib/**/*已包含，此步可跳过）

3. 验证声明文件内容正确性 #

确保声明文件的模块声明语法正确，示例：

// xyz.d.ts
declare module 'xyz' {
  export function someFunction(arg: string): void;
  // 其他类型定义
}

注意模块名必须与代码中import的名称完全一致（包括大小写）。

4. 清理CDK缓存并重新执行 #

执行以下命令清理缓存后再尝试synth：

rm -rf cdk.out
cdk synth

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