将Nest.js开发的Node.js应用部署到Heroku时出现TS2411报错如何解决

问题原因 #

该报错由@types/jsdom类型定义与项目TypeScript版本、全局Window类型声明不兼容导致。本地运行正常是因为Nest本地开发命令默认仅做增量编译/不执行全量类型校验，而Heroku部署阶段会自动执行npm run build触发完整TS编译校验，因此仅在部署时抛出错误。

排查与解决步骤 #

• 方案1：降级/移除@types/jsdom依赖
  目前已知v20.0.0以上版本的@types/jsdom会与4.9版本以下的TypeScript产生该类型冲突，你可以直接安装兼容版本：
  npm install @types/jsdom@19.0.3 --save-dev
  若你项目没有直接用到jsdom的类型定义，可直接将该依赖从devDependencies中移除。如果该依赖是其他包间接引入的，可在package.json中添加配置强制锁定版本：

  "overrides": {
    "@types/jsdom": "19.0.3"
  }
  

• 方案2：配置TS跳过第三方库类型检查
  打开项目根目录的tsconfig.json，在compilerOptions节点下添加如下配置：

  "skipLibCheck": true
  

  该配置仅跳过node_modules下的类型文件校验，不会影响业务代码的类型检查，是第三方依赖类型冲突最通用的解决方案。

• 方案3：对齐本地与Heroku的环境版本
  在package.json中添加引擎配置，避免Heroku使用非指定版本的Node.js和npm产生环境差异：

  "engines": {
    "node": "17.0.1",
    "npm": "8.1.0"
  }
  

以上修改完成后，执行heroku builds:cache:purge -a 你的Heroku应用名称清理构建缓存，再重新推送代码即可。

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