安装、配置和集成本地模拟器套件

您可以针对不同的原型设计和测试环境(从一次性原型设计会话到生产规模级的持续集成工作流)安装和配置 Firebase 本地模拟器套件。

安装本地模拟器套件

在安装 Emulator Suite 之前,您需要具备:

  • Node.js 8.0 或更高版本。
  • Java 1.8 或更高版本。

要安装 Emulator Suite,请执行以下操作:

  1. 安装 Firebase CLI。如果您尚未安装 Firebase CLI,请立即安装。 您需要安装 CLI 8.14.0 或更高版本才能使用 Emulator Suite。可以使用以下命令检查已安装的版本:
    firebase --version
  2. 如果您尚未执行此操作,请将当前工作目录初始化为 Firebase 项目,并按照屏幕上的提示指定要使用的产品:
    firebase init
  3. 设置模拟器套件。此命令会启动配置向导,让您选择感兴趣的模拟器,下载相应的模拟器二进制文件,以及在默认设置不合适时设置模拟器端口。
    firebase init emulators

安装模拟器后,系统将不会执行更新检查,并且在您更新 Firebase CLI 版本之前不会进行额外的自动下载。

配置 Emulator Suite

您可以选择在 firebase.json 文件中配置模拟器的网络端口和安全规则定义的路径:

  • 可通过运行 firebase init emulators 或手动修改 firebase.json 来更改模拟器端口。
  • 可通过手动修改 firebase.json 以更改安全规则定义的路径。

如果您不配置这些设置,则模拟器将侦听其默认端口,而 Cloud Firestore、Realtime Database 和 Cloud Storage 模拟器将需要在运行的同时确保开放数据的安全性。

命令 说明
init emulators 启动模拟器初始化向导。确定要安装的模拟器,并视需要指定模拟器端口设置。init emulators 没有破坏性;接受默认值将保留当前的模拟器配置。

端口配置

每个模拟器都将绑定到您的机器上具有首选默认值的不同端口。

模拟器 默认端口
Authentication 9099
Emulator Suite 界面 4000
Cloud Functions 5001
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage 9199
Firebase Hosting 5000
Pub/Sub 8085

安全规则配置

模拟器将通过 firebase.json 中的 databasefirestorestorage 配置键来采用安全规则配置。

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore" {
    "rules": "firestore.rules"
  },
  "storage" {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

启动模拟器

您可以启动模拟器并使其保持运行状态,直到手动将其终止,或者使其在指定测试脚本的持续时间内运行,然后自动关闭。

命令 说明
emulators:start 启动在 firebase.json 中配置的 Firebase 产品的模拟器。 模拟器进程将继续运行,直到您明确将其停止。调用 emulators:start 会将模拟器下载到 ~/.cache/firebase/emulators/(如果模拟器尚未安装)。
标志 说明
--only 可选。限制可启动的模拟器。提供以英文逗号分隔的模拟器名称列表,指定“auth”、“database”、“firestore”、“functions”、“hosting”或“pubsub”中的一个或多个名称。
--inspect-functions debug_port 可选。与 Cloud Functions 模拟器结合使用,以在指定端口(如果省略了参数,则为默认端口 9229)启用函数的断点调试。请注意,在提供此标志时,Cloud Functions 模拟器将切换到特殊的序列化执行模式,在这种模式下,函数在单个进程中按顺序(先进先出)执行;这样可以简化函数调试,但其行为不同于云端中函数的多进程并行执行。
--export-on-exit= 可选。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器搭配使用。指示模拟器在关停时将数据导出到目录,如针对 emulators:export 命令的内容所述。可以使用以下标志指定导出目录:firebase emulators:start --export-on-exit=./saved-data。 如果使用 --import,导出路径将默认相同;例如:firebase emulators:start --import=./data-path --export-on-exit。最后,如果需要,您可以将不同的目录路径传递给 --import--export-on-exit 标志。
--import=import_directory 可选。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器搭配使用。将使用 --export-on-exit 启动选项或 emulators:export 命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器实例。当前存储在模拟器内存中的任何数据都将被覆盖。
emulators:exec scriptpath 为在 firebase.json 中配置的 Firebase 产品启动模拟器后,在 scriptpath 中运行脚本。模拟器进程将在脚本运行完毕后自动停止。
标志 说明
--only 可选。限制可启动的模拟器。提供以英文逗号分隔的模拟器名称列表,指定“firestore”、“database”、“functions”、“hosting”或“pubsub”中的一个或多个名称。
--inspect-functions debug_port 可选。与 Cloud Functions 模拟器结合使用,以在指定端口(如果省略了参数,则为默认端口 9229)启用函数的断点调试。请注意,在提供此标志时,Cloud Functions 模拟器将切换到特殊的序列化执行模式,在这种模式下,函数在单个进程中按顺序(先进先出)执行;这样可以简化函数调试,但其行为不同于云端中函数的多进程并行执行。
--export-on-exit= 可选。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器搭配使用。指示模拟器在关停时将数据导出到目录,如针对 emulators:export 命令的内容所述。可以使用以下标志指定导出目录:firebase emulators:start --export-on-exit=./saved-data。 如果使用 --import,导出路径将默认相同;例如:firebase emulators:start --import=./data-path --export-on-exit。最后,如果需要,您可以将不同的目录路径传递给 --import--export-on-exit 标志。
--import=import_directory 可选。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器搭配使用。将使用 --export-on-exit 启动选项或 emulators:export 命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器实例。当前存储在模拟器内存中的任何数据都将被覆盖。
--ui 可选。在执行期间运行模拟器界面。

firebase emulators:exec 方法通常更适合持续集成工作流。

导出和导入模拟器数据

您可以从 Authentication、Cloud Firestore、Realtime Database 和 Cloud Storage 模拟器中导出数据,以将其用作可共享的通用基准数据集。如上所述,可以使用 --import 标志导入这些数据集。

emulators:export export_directory

Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器。从正在运行的 Cloud Firestore、Realtime Database 或 Cloud Storage 模拟器实例导出数据。如果指定的 export_directory 尚不存在,系统将创建一个。如果指定的目录存在,系统会提示您确认是否应覆盖之前的导出数据。您可以使用 --force 标志跳过此提示。导出目录包含数据清单文件 firebase-export-metadata.json

您可以使用上述 --export-on-exit 标志指示模拟器在关停时自动导出数据。

与 CI 系统集成

运行容器化的模拟器套件映像

在典型的 CI 设置中,安装和配置使用容器的模拟器套件非常简单。

请注意以下几个问题:

  • JAR 文件已在 ~/.cache/firebase/emulators/ 安装并缓存。

    • 您可能需要将此路径添加到 CI 缓存配置,以避免重复下载。
  • 如果您的代码库中没有 firebase.json 文件,则必须向 emulators:startemulators:exec 命令添加命令行参数以指定应启动的模拟器。例如,
    --only functions,firestore

生成身份验证令牌(仅限托管模拟器)

如果您的持续集成工作流依赖于 Firebase 托管,那么您需要使用令牌登录才能运行 firebase emulators:exec。其他模拟器不需要登录。

要生成令牌,请在本地环境中运行 firebase login:ci;不得通过 CI 系统执行此操作。按照说明进行身份验证。您仅需对每个项目执行一次此步骤,因为令牌在各个版本中都有效。令牌应被视为密码;请务必保密。

如果您的 CI 环境允许您指定可在构建脚本中使用的环境变量,则只需创建一个名为 FIREBASE_TOKEN 的环境变量,其值为访问令牌字符串。Firebase CLI 会自动选择 FIREBASE_TOKEN 环境变量,而模拟器将正常启动。

作为最后的补救手段,您可以直接在构建脚本中包含令牌,但要确保不受信任方没有访问权限。对于这种硬编码方法,您可以将 --token "YOUR_TOKEN_STRING_HERE" 添加到 firebase emulators:exec 命令中。

使用模拟器中心 REST API

列出正在运行的模拟器

要列出当前正在运行的模拟器,请向模拟器中心的 /emulators 端点发送 GET 请求。

curl localhost:4400/emulators

结果将是一个 JSON 对象,其中会列出所有正在运行的模拟器及其主机/端口配置,例如:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

启用/停用后台函数触发器

在某些情况下,您需要暂时停用本地函数触发器。 例如,您可能希望删除 Cloud Firestore 模拟器中的所有数据,但不触发 Cloud Functions 模拟器中运行的任何 onDelete 函数。

要暂时停用本地函数触发器,请向模拟器中心的 /functions/disableBackgroundTriggers 端点发送 PUT 请求。

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

结果将是一个详细说明当前状态的 JSON 对象。

{
  "enabled": false
}

要在本地函数触发器被停用后将其启用,请向模拟器中心的 /functions/enableBackgroundTriggers 端点发送 PUT 请求。

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

结果将是一个详细说明当前状态的 JSON 对象。

{
  "enabled": true
}

模拟器 SDK 集成

本部分中的表格指明了客户端 SDK 和 Admin SDK 支持哪些模拟器。“未来”表示计划支持此模拟器但目前尚不支持。

客户端 SDK 可用性

Android iOS Web Firebase 界面
Android
Firebase 界面
iOS
Firebase 界面
Web
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 未来 不适用
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 未来 不适用
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 未来 Future
Cloud Storage 20.0.0 8.0.0 8.4.0 不适用 不适用 不适用
Cloud Functions 19.1.0 7.2.0 8.0.0 不适用 不适用 不适用
Hosting 不适用 不适用 不适用 不适用 不适用 不适用

Admin SDK 可用性

Node Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 未来
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 未来 未来 Future
Cloud Storage 9.8.0 Future 未来 未来
Cloud Functions 不适用 不适用 不适用 不适用
Hosting 不适用 不适用 不适用 不适用