Express/TS/Apollo中Request类型无user/auth属性的编译错误排查

核心概念梳理 #

作为PHP转TS的开发者，首先要明确TS和PHP的核心差异：

• PHP是动态类型语言，运行时可以随意给对象添加属性；但TS是静态类型语言，编译时就会检查属性是否存在于类型定义中。
• Express的Request类型（来自@types/express）默认没有auth或user属性，所以即使express-jwt在运行时把解码后的JWT载荷挂载到了req.auth，TS编译阶段依然不认这个属性，就会抛出Property 'auth' does not exist on type 'Request'的错误。
• TS允许扩展现有类型（称为模块合并），但必须遵循正确的声明规则，否则只会在编辑器层面消除提示，编译时依然报错。

分步解决方案 #

1. 编写正确的全局类型扩展文件 #

在项目根目录创建types/express/index.d.ts（目录不存在就新建），写入以下代码：

import { JwtPayload } from 'jsonwebtoken';

declare global {
  namespace Express {
    // 扩展Express的Request接口，添加auth属性
    interface Request {
      // 用?表示该属性可能不存在（比如未登录的请求）
      auth?: JwtPayload;
      // 如果你的JWT载荷有自定义字段，比如userId、role，可以替换成自定义接口：
      // auth?: { userId: string; role: string } & JwtPayload;
    }
  }
}

// 必须导出空对象，让TS识别这个文件为模块，否则全局扩展不生效
export {};

2. 配置tsconfig.json识别自定义类型 #

修改tsconfig.json，确保自定义类型目录被TS扫描到：

{
  "compilerOptions": {
    // 其他编译选项保持不变
    "typeRoots": ["./node_modules/@types", "./types"],
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*",
    "types/**/*" // 加入自定义类型目录
  ]
}

3. 确认express-jwt的配置 #

确保你使用的是最新版express-jwt（注意现在包名是express-jwt，导入方式是import { expressjwt } from 'express-jwt'），示例配置：

import { expressjwt } from 'express-jwt';
import express from 'express';

const app = express();

// 全局应用JWT认证中间件，排除登录等不需要认证的路由
app.use(
  expressjwt({
    secret: process.env.JWT_SECRET!, // 你的JWT密钥，注意非空断言
    algorithms: ['HS256'], // 和认证微服务使用的算法一致
  }).unless({ path: ['/api/auth/login'] })
);

4. 在Apollo Context中传递认证信息 #

在创建ApolloServer并挂载到Express时，从req中获取auth并传入Context：

import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { typeDefs, resolvers } from './graphql';

async function startServer() {
  const server = new ApolloServer({ typeDefs, resolvers });
  await server.start();

  app.use(
    '/graphql',
    express.json(),
    expressMiddleware(server, {
      context: async ({ req }) => {
        // 现在TS会识别req.auth属性，编译不会报错
        return { user: req.auth };
      },
    })
  );

  app.listen(4000, () => console.log('Server running on port 4000'));
}

startServer();

常见问题排查 #

• 如果依然编译报错：检查tsconfig.json的include是否包含了types/**/*，或者尝试重启TS服务器（VSCode中按Ctrl+Shift+P，选择TypeScript: Restart TS Server）。
• 自定义JWT载荷类型：如果你的JWT包含userId、username等自定义字段，可以扩展JwtPayload接口，让TS提供更精准的类型提示。

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