Firebase Functions v2中App Check验证中间件验证失败问题排查

我按照Firebase官方推荐方式实现Token验证的App Check中间件，用Postman测试时始终返回401 Unauthorized。已在请求头携带X-Firebase-AppCheck Token，但verifyToken方法始终验证失败。相关代码如下：

中间件代码 #

import {request, response, NextFunction} from "express";
import {getAppCheck} from "firebase-admin/app-check";

export const appCheckVerification =
  async (req = request, res = response, next: NextFunction) => {
    const appCheckToken = req.header("X-Firebase-AppCheck");

    if (!appCheckToken) {
      res.status(401);
      return next("Unauthorized");
    }

    try {
      const appCheckClaims = await getAppCheck().verifyToken(appCheckToken);
      // If verifyToken() succeeds, continue with the next middleware
      // function in the stack.
      return next();
    } catch (err) {
      res.status(401);
      return next("Unauthorized");
    }
  };

端点配置代码 #

import {onRequest} from "firebase-functions/v2/https";
import * as express from "express";
import * as admin from "firebase-admin";

admin.initializeApp();
const app = express();

app.get("/", [appCheckVerification], myEndpoint);

exports.myEndpoint = onRequest(app);

可能的问题原因及排查步骤 #

• Token有效性问题

  • 确认Token是从对应平台的App Check SDK正确获取，而非手动伪造或已过期（默认有效期1小时）。
  • 检查Token复制时是否存在多空格、遗漏字符等篡改情况。

• Admin SDK配置问题

  • 验证Firebase Admin SDK初始化所用的服务账号，是否拥有App Check Token Verifier权限。
  • 本地开发时，确认GOOGLE_APPLICATION_CREDENTIALS环境变量已正确指向有效服务账号密钥文件。
  • 核对Admin SDK与App Check SDK的版本兼容性，避免版本不匹配引发验证逻辑错误。

• 请求头传递问题

  • 在Postman中确认请求头键名为X-Firebase-AppCheck，完全匹配大小写（HTTP头虽不区分大小写，但部分框架可能严格处理）。
  • 检查请求头Token值是否完整，无额外换行或空格。
  • 可在中间件中打印appCheckToken，确认服务端是否接收到正确的Token。

• Firebase项目配置问题

  • 确认Firebase控制台已开启App Check，并配置了对应验证提供者（如ReCAPTCHA v3、App Attest等）。
  • 检查App Check允许列表，确保测试设备/来源未被拦截。
  • 确认Google Cloud控制台已启用项目的App Check API。

• 代码逻辑细节问题

  • 检查getAppCheck()是否正确获取到App Check实例，无初始化失败情况。
  • 在catch块中打印错误详情（如console.error(err)），查看具体失败原因（无效签名、项目ID不匹配等），不要直接返回泛化的401。

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