启用AppCheck的Firebase云函数返回401未授权问题排查

问题背景 #

部署集成createCompany云函数的Flutter Web应用后，模拟器运行正常，但线上环境调用该函数返回401 - Unauthorized。移除云函数的enforceAppCheck: true配置后恢复正常，说明问题出在AppCheck验证环节。已在Firebase控制台填写reCAPTCHA密钥，且配置了云控制台调用者权限。

相关配置代码 #

1. Flutter初始化代码（main函数） #

await Firebase.initializeApp(
  options: DefaultFirebaseOptions.currentPlatform,
);
AndroidProvider provider = AndroidProvider.playIntegrity;
if (kDebugMode) {
  provider = AndroidProvider.debug;
}
await FirebaseAppCheck.instance.activate(
  webRecaptchaSiteKey: '<My actual site key here>',
  androidProvider: provider,
);

2. Flutter云函数调用代码 #

Future<String> createCompany(String firstName, String lastName) async {
    var result = await FirebaseFunctions.instance
        .httpsCallable('createCompany')
        .call(<String, dynamic>{'firstName': firstName, 'lastName': lastName});
    return result.data["company"];
}

3. Firebase云函数代码 #

exports.createCompany = functions.runWith({
      enforceAppCheck: true
    })
      .https.onCall(async (data, context) => {
        
        functions.logger.log("createCompany start");
        
        if (context.app == undefined) {
          throw new functions.https.HttpsError(
            'failed-precondition',
            'The function must be called from an App Check verified app.')
        }
// ... 业务逻辑代码

需补充的配置与排查步骤 #

• 确认reCAPTCHA版本与域名绑定：
  必须使用reCAPTCHA v3密钥，v2无法适配Firebase AppCheck。同时在Google reCAPTCHA控制台中，将生产环境的HTTPS域名（含子域名）添加到允许列表，确保域名完全匹配。
• 验证Web端AppCheck令牌传递：
  打开Chrome开发者工具「网络」面板，查看createCompany请求的请求头，确认存在X-Firebase-AppCheck字段且携带有效令牌。如果没有，检查FirebaseAppCheck.instance.activate()是否在函数调用前执行完成。
• 核对云函数调用者权限：
  在Firebase控制台「App Check」→「调用者」页面，确认你的Web应用已被添加为createCompany函数的授权调用者，且状态为「已启用」。
• 确保云函数区域匹配：
  Flutter中初始化的Firebase Functions区域要和云函数部署的区域一致。若部署时指定了区域（如us-central1），Flutter端需通过配置对齐区域。
• 检查生产环境AppCheck模式：
  确认生产环境未误开启kDebugMode，确保Web端使用reCAPTCHA而非debug提供者。
• 查看云函数详细日志：
  在Firebase控制台云函数日志中，查看context.app的具体值。若为undefined，说明令牌验证失败，需排查令牌生成（reCAPTCHA密钥有效性）或传递环节。

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