Firebase本地Functions模拟器出现401未授权错误求助

问题场景 #

项目已配置Firebase模拟器，Auth、Firestore等其他服务运行正常，但调用Functions时持续返回401 Unauthenticated错误。以下是相关配置细节：

应用初始化与Functions配置 #

import { initializeApp, getApp } from 'firebase/app'
import { getFunctions, httpsCallable, connectFunctionsEmulator } from 'firebase/functions'

export const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_AUTH_DOMAIN,
  databaseURL: process.env.NEXT_PUBLIC_DATABASE_URL,
  projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_APP_ID,
  measurementId: process.env.NEXT_PUBLIC_MEASUREMENT_ID
}

function createFirebaseApp(firebaseConfig) {
  try {
    return getApp()
  } catch {
    return initializeApp(firebaseConfig)
  }
}
const functions = getFunctions(firebaseApp)

export const createCustomer = httpsCallable(functions, 'createCustomer')

firebase.json模拟器配置 #

"emulators": {
    "auth": {
      "port": 9099
    },
    "functions": {
      "port": 5001
    },
    "firestore": {
      "port": 8080
    },
    "database": {
      "port": 9000
    },
    "hosting": {
      "port": 5002
    },
    "storage": {
      "port": 9199
    },
    "ui": {
      "enabled": true
    },
    "singleProjectMode": true
  },

本地模拟器连接配置 #

if (process.env.NODE_ENV === 'development') {
  connectAuthEmulator(auth, 'http://127.0.0.1:9099')
  connectFunctionsEmulator(functions, '127.0.0.1', 5001)
  connectFirestoreEmulator(db, '127.0.0.1', 8080)
  connectStorageEmulator(storage, '127.0.0.1', 9199)
}

错误现象与日志 #

• 浏览器请求地址：http://127.0.0.1:5001/my-project-dev/us-central1/createCustomer，返回401 (Unauthorized)
• Functions日志显示认证验证通过：

20:18:23 Beginning execution of "us-central1-createCustomer"
{
  "key": "x-callable-context-auth",
  "value": " -- removed for privacy -- ",
  "severity": "DEBUG",
  "message": "Callable functions auth override"
}
20:18:23 function[us-central1-createCustomer]
{
  "verifications": {
    "app": "MISSING",
    "auth": "VALID"
  },
  "logging.googleapis.com/labels": {
    "firebase-log-type": "callable-request-verification"
  },
  "severity": "DEBUG",
  "message": "Callable request verification passed"
}

排查与修复要点 #

1. 补全App区域与身份配置 #

日志中"app": "MISSING"提示App身份验证缺失：

• 调用getFunctions时指定函数部署的区域，避免区域不匹配：

  const functions = getFunctions(firebaseApp, 'us-central1')
  

• 确认firebaseConfig中的apiKey、projectId与本地模拟器使用的项目完全一致

2. 本地开发跳过App Check验证 #

如果Functions启用了App Check，本地模拟器默认无法通过验证：

• 在Functions代码中添加本地跳过逻辑：

  exports.createCustomer = functions.https.onCall(async (data, context) => {
    // 本地开发环境跳过App Check
    if (process.env.FUNCTIONS_EMULATOR === 'true') {
      // 执行业务逻辑
    } else {
      // 生产环境App Check验证逻辑
    }
  })
  

• 或启动模拟器时添加环境变量强制跳过：

  firebase emulators:start --env-vars APP_CHECK_BYPASS=true
  

3. 确认认证状态同步 #

尽管日志显示auth: VALID，仍需确保：

• 前端调用createCustomer前已通过Auth模拟器完成登录（使用测试账号）
• connectAuthEmulator的调用时机早于Functions初始化，避免认证令牌未同步到请求

4. 清除缓存与排查跨域 #

• 清除浏览器缓存或使用无痕模式测试，避免旧令牌干扰
• 确认模拟器默认跨域配置未被自定义拦截（Firebase模拟器自动处理跨域，无需额外配置）

5. 升级依赖版本 #

旧版本CLI或SDK可能存在兼容问题：

• 升级Firebase CLI：npm install -g firebase-tools
• 升级项目Firebase SDK：npm install firebase@latest

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