GitHub Actions中Python项目运行Firestore模拟器报凭证错误如何解决

核心是Python版Google Cloud Firestore SDK的行为和Node.js版存在两个关键差异，对应需要补充两个缺失配置：

1. 未等待模拟器完全启动就执行测试 #

你当前配置中模拟器以&后台启动后立刻执行pytest，很可能出现8080端口尚未完成监听就运行测试的情况，SDK检测不到可用模拟器就会 fallback 去查找生产环境凭证，触发报错。
解决方法：增加端口等待逻辑，推荐使用node生态的wait-on工具（你已经配置了Node.js环境可直接使用），修改启动模拟器的步骤：

- name: Start Firestore emulator
  run: |
    npm i -g firebase firebase-tools wait-on
    firebase setup:emulators:firestore
    firebase emulators:start --only firestore --project test-project-id &
    npx wait-on tcp:8080

这里额外给模拟器启动指定--project参数，和后续SDK配置的项目ID保持一致，避免额外兼容问题。

2. Python SDK需要显式指定项目ID #

Node.js SDK检测到FIRESTORE_EMULATOR_HOST环境变量时，会自动使用默认占位项目ID，不需要额外配置；但Python SDK要求必须显式传入项目ID，否则会直接触发默认凭证查找逻辑，和是否启用模拟器无关。
解决方法分两步：

• 在pytest执行步骤的环境变量中增加GOOGLE_CLOUD_PROJECT，值可以随便填任意字符串，不需要是真实的GCP项目ID
• 检查你的Firestore客户端初始化代码，确保适配模拟器场景：
  修改后的pytest执行步骤配置：

- name: Test with pytest
  run: |
    pytest
  env:
    FIRESTORE_EMULATOR_HOST: localhost:8080
    GOOGLE_CLOUD_PROJECT: test-project-id

如果你的代码中是显式初始化Firestore客户端，补充适配逻辑即可：

import os
from google.cloud import firestore

if os.getenv("FIRESTORE_EMULATOR_HOST"):
    # 模拟器环境无需真实凭证，传入任意项目ID即可正常运行
    db = firestore.Client(project=os.getenv("GOOGLE_CLOUD_PROJECT", "test-project-id"))
else:
    # 生产环境走默认凭证逻辑
    db = firestore.Client()

可选验证 #

如果以上配置完成还是报错，可以升级google-cloud-firestore依赖到最新版本，旧版本的SDK存在模拟器检测逻辑异常的问题：

pip install --upgrade google-cloud-firestore

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