安装Firebase Admin SDK后Node.js TypeScript报错求助

1. JWT解码后自定义属性的类型问题 #

问题根源 #

firebase-admin的verifyIdToken方法返回的DecodedIdToken类型为string | JwtPayload，默认JwtPayload接口不包含自定义的id和role字段，TypeScript无法识别这些非标准属性，导致编译报错。

解决办法 #

方式一：扩展全局JwtPayload类型

在项目根目录创建类型声明文件（比如firebase-extensions.d.ts），通过类型声明合并扩展Firebase的JwtPayload接口：

import { JwtPayload } from 'firebase-admin/lib/auth/token-verifier';

declare module 'firebase-admin/lib/auth/token-verifier' {
  interface JwtPayload {
    id: string;
    role: string;
  }
}

配置后，TypeScript会自动识别decodedToken上的id和role属性，无需额外类型断言。

方式二：用类型守卫窄化类型

若不想修改全局类型，可在中间件中添加类型守卫，确保decodedToken符合自定义结构：

import { JwtPayload } from 'firebase-admin/auth';

function isCustomTokenPayload(token: string | JwtPayload): token is JwtPayload & { id: string; role: string } {
  return typeof token !== 'string' && 'id' in token && 'role' in token;
}

// 中间件内使用示例
const decodedToken = await admin.auth().verifyIdToken(idToken);
if (!isCustomTokenPayload(decodedToken)) {
  throw new Error('令牌缺少自定义字段');
}
// 此处可安全访问decodedToken.id和decodedToken.role
req.user = { id: decodedToken.id, role: decodedToken.role };

2. bodyParser类型不匹配问题 #

问题根源 #

firebase-admin@12.x引入的类型定义可能与@types/express或body-parser的类型发生冲突，导致Express请求的body类型推断异常。

解决办法 #

方式一：显式指定Request的Body类型

在路由或中间件中，手动声明请求体的类型：

import { Request, Response } from 'express';

// 定义你的请求体结构
interface LoginRequestBody {
  username: string;
  password: string;
}

app.post('/login', (req: Request<{}, {}, LoginRequestBody>, res: Response) => {
  const { username, password } = req.body; // 此处类型推断正常
  // 业务逻辑处理
});

方式二：对齐依赖版本

检查package.json中的类型依赖，确保@types/express与firebase-admin版本兼容。推荐锁定@types/express到最新稳定版，示例配置：

{
  "dependencies": {
    "express": "^4.18.2",
    "firebase-admin": "^12.1.1",
    "body-parser": "^1.20.2"
  },
  "devDependencies": {
    "@types/express": "^4.17.21",
    "@types/node": "^20.11.0",
    "typescript": "^5.3.3"
  }
}

执行npm install重新安装依赖，覆盖冲突的类型文件。

方式三：临时排除冲突类型（不推荐长期使用）

若冲突来自firebase-admin的特定类型文件，可在tsconfig.json中临时排除：

{
  "compilerOptions": {
    // 其他编译配置
  },
  "exclude": [
    "node_modules/firebase-admin/lib/auth/token-verifier.d.ts"
  ]
}

额外提示 #

• 确保生成Firebase自定义令牌时，确实已将id和role写入令牌 payload，否则即使编译通过，运行时仍会报错。
• 避免长期依赖skipLibCheck: true，该配置会掩盖真实的类型问题，仅适合临时调试场景。

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