本地运行 firebase 函数模拟器时出现 401 unauthenticated 错误，通常是因为生产环境启用的 app check 在开发环境下未正确绕过，导致可调用函数拒绝未验证请求。
本地运行 firebase 函数模拟器时出现 401 unauthenticated 错误，通常是因为生产环境启用的 app check 在开发环境下未正确绕过，导致可调用函数拒绝未验证请求。
当您在本地使用 Firebase Emulator Suite 并调用 httpsCallable 函数时，若函数配置了 enforceAppCheck: true（或默认启用），Emulator 不会自动跳过 App Check 验证——即使所有其他服务（Auth、Firestore 等）均已正确连接至模拟器。此时，客户端发出的请求虽经本地函数模拟器接收，但因缺少有效的 App Check token（本地调试环境无法生成合法 token），函数会在入口校验阶段直接返回 401 Unauthorized，而日志中仍显示 "auth": "VALID"（指 Firebase Auth 上下文有效），容易造成误导。
✅ 正确做法是：根据环境动态控制 App Check 强制策略。推荐在函数定义中显式判断 NODE_ENV 或使用 Firebase 提供的 isEmulator 标识：
import { getFunctions } from 'firebase/functions';
import { isEmulator } from 'firebase/util';
// 在函数端（Cloud Functions 代码中）
const isLocalEmulator = process.env.FUNCTIONS_EMULATOR === 'true';
exports.createCustomer = functions
.runWith({
enforceAppCheck: !isLocalEmulator, // 仅在非模拟器环境强制校验
secrets: ['STRIPE_SECRET_API_KEY']
})
.https.onCall(async (data, context) => {
// ✅ 此处 context.app 可安全使用（本地为 null，生产为有效 AppCheckToken）
if (!context.app && !isLocalEmulator) {
throw new functions.https.HttpsError(
'unauthenticated',
'App Check token is missing or invalid.'
);
}
return await createCustomer(data);
});
⚠️ 注意事项：
- 不要仅依赖
process.env.NODE_ENV === 'development'，因为 Functions 运行环境不继承前端环境变量；应优先使用process.env.FUNCTIONS_EMULATOR === 'true'（由firebase emulators:start自动注入）； - 客户端无需额外配置 App Check 实例来调用本地函数——
connectFunctionsEmulator()已隐式禁用 App Check 校验，但前提是函数端未强制启用； - 若使用 Firebase Admin SDK 在函数内校验 App Check，需确保
admin.initializeApp()后未意外启用 App Check 中间件； - 模拟器 UI（
http://localhost:4000）中可实时查看函数调用日志与错误详情，建议开启--debug模式启动：firebase emulators:start --debug。
? 总结：401 错误根源几乎总是服务端函数的 enforceAppCheck 配置未适配本地环境。通过条件化启用 App Check，并统一使用 FUNCTIONS_EMULATOR 环境变量作为判断依据，即可彻底解决本地调试时的认证拦截问题，同时保障生产环境的安全性。
