TypeScript扩展Express Request属性报TS2339错误如何解决

问题根因 #

类型扩展声明未被TypeScript编译器/ts-node正确加载，通常由三个问题导致：

• 类型声明文件写法错误，declare global使用场景不对
• tsconfig.json的include配置未覆盖自定义声明文件路径
• ts-node默认仅加载被业务代码import引入的文件，不会自动扫描全局类型声明

修复步骤 #

1. 修正类型声明文件
   在项目根目录（或你存放自定义类型的目录）新建express.d.ts文件：

• 如果该声明文件内没有任何import/export语句（纯声明文件），直接写如下内容，不要套declare global：

// express.d.ts
declare namespace Express {
  interface Request {
    user: string;
  }
}

• 如果声明文件内需要引入其他类型（也就是文件本身是ES模块），才需要套declare global，且文件末尾必须加空导出标记为模块：

// 示例：需要引入其他类型时的写法
import { UserType } from "./src/types/user";

declare global {
  namespace Express {
    interface Request {
      user: UserType;
    }
  }
}

export {};

2. 检查tsconfig.json配置
   确保include字段覆盖到你存放express.d.ts的路径，参考配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  },
  "include": [
    "src/**/*.ts",
    "*.d.ts" // 根目录下的d.ts文件必须被包含
  ]
}

如果你自定义了typeRoots配置，记得同时把./node_modules/@types和你的自定义类型目录加入列表，否则会丢失原生Express的类型定义。

3. 修正ts-node运行参数
   默认配置下ts-node不会自动加载tsconfig中include指定的未被引用的文件，运行时加上--files参数即可：

npx ts-node --files x.ts

如果不想每次加参数，可以在tsconfig中新增ts-node配置：

{
  "ts-node": {
    "files": true
  },
  "compilerOptions": {
    // 原有编译配置
  }
}

验证 #

修改完成后重启TS服务（编辑器里重启TypeScript Server，或者重新运行ts-node），req.user的类型提示会正常显示，不再报TS2339属性不存在的错误。

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