升级Node至20.16.0后@types相关TypeScript报错如何解决？

报错现象 #

升级Node版本到20.16.0后，出现两类TypeScript类型错误：

1. @types/express相关导出成员缺失报错：

   node_modules/@types/express-serve-static-core/index"' has no exported member 'CookieOptions'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'Errback'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'Application'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'Express'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'Handler'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'IRouter'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'IRouterHandler'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'IRouterMatcher'
   node_modules/@types/express-serve-static-core/index"' has no exported member 'MediaType'

2. @types/passport类型不兼容报错：

   Type 'Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>' does not satisfy the constraint 'IncomingMessage'.
   Type 'Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>' is missing the following properties from type 'IncomingMessage': aborted, httpVersion, httpVersionMajor, httpVersionMinor, and 45 more

问题原因 #

核心是依赖版本不匹配：

• 当前使用的typescript@3.7.4、@types/express@4.17.9版本过旧，无法适配Node 20的内置类型定义，同时express-serve-static-core的类型结构在后续版本有调整，旧版类型包与新版Node冲突。
• @nestjs@7.x本身仅支持Node 10/12/14，和Node 20的兼容性有限，进一步放大了类型不匹配问题。

解决步骤 #

1. 升级TypeScript到兼容版本 #

NestJS 7.x要求TypeScript版本在>=3.6.0 <4.0.0范围内，选择该区间内的最新稳定版（如3.9.10），避免老版本TS无法解析新类型：

npm install typescript@~3.9.10 --save-dev

2. 更新@types/express及相关类型包 #

旧版@types/express@4.17.9依赖的express-serve-static-core类型已过时，升级到4.17.x系列的最新稳定版（如4.17.21），修复导出成员缺失问题：

npm install @types/express@~4.17.21 --save-dev

3. 更新@types/passport版本 #

passport的类型定义依赖express的Request类型，升级到与新版@types/express兼容的版本：

npm install @types/passport@~1.0.16 --save-dev

4. 清理依赖缓存并重新安装 #

删除旧的依赖包和锁文件，避免缓存导致的版本冲突：

rm -rf node_modules package-lock.json
npm install

5. （可选）升级NestJS到更高版本 #

如果上述步骤后仍有报错，说明NestJS 7.x与Node 20的兼容性问题无法通过类型包升级解决，可考虑升级到NestJS 8.x（支持Node 12+，包括Node 20）：

• 升级NestJS核心依赖：

  npm install @nestjs/common@^8.0.0 @nestjs/config@^8.0.0 @nestjs/core@^8.0.0 @nestjs/microservices@^8.0.0 @nestjs/platform-express@^8.0.0 --save
  

• 同步升级TypeScript到4.x兼容版本：

  npm install typescript@~4.5.5 --save-dev
  

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