Yarn升级至v3.2.2后TypeScript模块声明失效求助

问题根源 #

Yarn v3默认启用PnP（Plug'n'Play）模式替代传统node_modules，这改变了TypeScript解析类型文件的路径逻辑，导致你自定义的Express Request扩展声明无法被正确识别合并。

解决方案 #

1. 调整自定义类型声明写法 #

改用全局命名空间扩展的标准写法，确保TypeScript能正确合并类型：

// src/types/express/Request.d.ts
import { ClientSession, MongoClient } from "mongodb";

declare global {
  namespace Express {
    interface Request {
      dbClient: MongoClient;
      dbSession: ClientSession;
      logger: typeof console; // 修正：console是实例，类型需用typeof console
    }
  }
}

// 必须添加此行，确保文件被识别为模块而非全局脚本
export {};

2. 修正tsconfig.json的路径配置 #

确保类型文件被TypeScript正确扫描：

• 将include改为通配符形式，覆盖src下所有子目录：

  "include": [
    "./src/**/*"
  ]
  

• 补充官方类型包路径到typeRoots（可选，提升PnP模式下的类型解析稳定性）：

  "typeRoots": [
    "./src/types",
    "./node_modules/@types"
  ]
  

3. 重新配置Yarn TypeScript SDK #

PnP模式下需确保编辑器和TypeScript使用Yarn提供的SDK：

# 重新生成适配编辑器的SDK
yarn dlx @yarnpkg/sdks vscode

如果用VS Code，记得通过右下角的TypeScript版本选择器，切换为Yarn提供的版本，而非编辑器内置版本。

4. 临时切换回node_modules验证（排查用） #

如果以上方法无效，可临时切回传统模式确认问题根源：
在项目根目录创建/修改.yarnrc.yml：

nodeLinker: node-modules

执行yarn install后再跑yarn tsc，若错误消失，说明问题来自PnP的类型解析逻辑，可针对性调整PnP配置。

5. 重置Yarn TypeScript插件 #

确保插件与你的TS版本兼容：

yarn plugin remove typescript
yarn plugin import typescript

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