安装@types/passport-google-oauth20致Express自定义Request接口类型冲突如何解决？

问题根源 #

安装@types/passport-google-oauth20后，该包的全局类型增强会修改Express/Passport的默认User或Request类型，其中Profile的id（字符串类型的Google用户ID）和你自定义的user.id（应用内用户ID，通常为数字或其他类型）形成类型冲突。使用交集类型&无法解决，因为TypeScript会将冲突的类型合并为never，导致报错。

解决方案 #

1. 显式定义独立的应用内用户类型 #

先创建自己的用户类型，完全和Passport的Profile/User类型隔离：

// src/types/app.ts
export interface AppUser {
  id: number; // 应用内用户ID，明确类型
  email: string;
  name: string;
  // 其他自定义属性
}

export interface Admin {
  isSuperAdmin: boolean;
  // 其他管理员属性
}

2. 正确扩展Express Request接口 #

在自定义类型声明文件中，直接覆盖Request的user属性为你的AppUser类型，避免隐式类型合并：

// src/types/express/index.d.ts
import { AppUser, Admin } from '../app';

declare global {
  namespace Express {
    interface Request {
      user: AppUser; // 显式指定为自定义用户类型
      admin?: Admin;
    }
  }
}

3. 配置TypeScript优先识别自定义类型 #

确保tsconfig.json包含你的类型文件，并设置typeRoots优先读取本地类型：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "typeRoots": ["./src/types", "./node_modules/@types"], // 本地类型优先
    "esModuleInterop": true,
    "skipLibCheck": true,
    "strict": true
  },
  "include": ["src/**/*"] // 包含所有src下的文件，包括类型声明
}

4. 显式指定Passport的User类型 #

如果Passport的默认User类型仍在干扰，直接将其扩展为你的AppUser类型：

// src/types/passport.d.ts
import { AppUser } from './app';

declare global {
  namespace Express {
    interface User extends AppUser {}
  }
}

5. Passport策略中明确返回自定义用户类型 #

在Google OAuth策略回调中，确保返回的是你的AppUser类型，避免类型推断错误：

passport.use(
  new GoogleStrategy(
    {
      clientID: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      callbackURL: '/auth/google/callback'
    },
    async (accessToken, refreshToken, profile, done) => {
      // 根据Google的profile查询或创建应用内用户
      let user = await User.findOne({ where: { googleId: profile.id } });
      if (!user) {
        user = await User.create({
          googleId: profile.id,
          email: profile.emails![0].value,
          name: profile.displayName
        });
      }
      // 这里user是AppUser类型，直接返回
      done(null, user);
    }
  )
);

关键说明 #

不要用交集类型Request & { user: AppUser }来扩展，因为全局已有Request.user的类型定义，交集会把冲突的id类型（Google的string vs 你的number）合并为never，导致TypeScript报错。显式覆盖类型是最直接的解决方式。

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