获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

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

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Firebase Local Emulator Suite 可以针对不同的原型和测试环境进行安装和配置,从一次性原型制作会话到生产规模的持续集成工作流。

安装本地模拟器套件

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

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

要安装模拟器套件:

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

安装模拟器后,在您更新 Firebase CLI 版本之前,不会执行更新检查,也不会发生额外的自动下载。

配置模拟器套件

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

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

如果您不配置这些设置,模拟器将在其默认端口上侦听,并且 Cloud Firestore、实时数据库和 Cloud Storage for Firebase 模拟器将在开放数据安全的情况下运行。

命令描述
初始化模拟器启动模拟器初始化向导。识别要安装的模拟器,并可选择指定模拟器端口设置。 init emulators是非破坏性的;接受默认值将保留当前的模拟器配置。

端口配置

每个模拟器使用首选默认值绑定到您机器上的不同端口。

模拟器默认端口
验证9099
模拟器套件用户界面4000
云函数5001
事件弧9299
实时数据库9000
云防火墙8080
Firebase 的云存储9199
Firebase 托管5000
发布/订阅8085

项目ID配置

根据您调用模拟器的方式,您可以使用不同的 Firebase 项目 ID 运行多个模拟器实例,也可以为给定项目 ID 运行多个模拟器实例。在这种情况下,模拟器实例在单独的环境中运行。

为所有模拟器调用设置一个项目 ID 通常是一种很好的做法,因此 Emulator Suite UI、不同的产品模拟器以及特定模拟器的所有正在运行的实例都可以在所有情况下正确通信。

Local Emulator Suite 在检测到环境中的多个项目 ID 时会发出警告,但您可以通过在firebase.json singleProjectMode键设置为false来覆盖此行为。

您可以检查项目 ID 声明中的不匹配项:

  • 命令行中的默认项目。默认情况下,项目 ID 将在启动时从使用firebase initfirebase use选择的项目中获取。要查看项目列表(并查看选择了哪一个),请使用firebase projects:list
  • 规则单元测试。项目 ID 通常在对规则单元测试库方法initializeTestEnvironmentinitializeTestApp的调用中指定。
  • 命令行--project标志。传递 Firebase CLI --project标志会覆盖默认项目。您需要确保标志的值与单元测试和应用程序初始化中的项目 ID 匹配。

还要检查您在配置Apple 平台AndroidWeb项目时设置的特定于平台的项目 ID 配置。

安全规则配置

模拟器将从databasefirestorefirebase.json中的storage配置键中获取安全规则配置。

{
  // 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": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "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"
    }
  }
}

指定 Java 选项

实时数据库模拟器、Cloud Firestore 模拟器和 Cloud Storage for Firebase 模拟器的一部分基于 Java,可以通过环境变量JAVA_TOOL_OPTIONS使用 JVM 标志进行自定义。

例如,如果您遇到与 Java 堆空间相关的错误,您可以将最大 Java 堆大小增加到 4GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

可以在用空格分隔的引号中指定多个标志,例如JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" 。这些标志仅影响模拟器的基于 Java 的组件,对 Firebase CLI 的其他部分没有影响,例如 Emulator Suite UI。

启动模拟器

您可以启动模拟器运行直到手动终止,或者运行指定的测试脚本持续时间然后自动关闭。

命令描述
模拟器:开始为 firebase.json 中配置的firebase.json产品启动模拟器。模拟器进程将继续运行,直到明确停止。调用emulators:start会将模拟器下载到 ~/.cache/firebase/emulators/ 如果它们尚未安装。
旗帜说明
--only可选的。限制哪些模拟器启动。提供以逗号分隔的模拟器名称列表,指定“auth”、“database”、“firestore”、“functions”、“hosting”或“pubsub”中的一个或多个。
--inspect-functions debug_port可选的。与 Cloud Functions 模拟器一起使用可在指定端口(或默认端口 9229,如果省略参数)启用函数的断点调试。请注意,当提供此标志时,Cloud Functions 模拟器会切换到特殊的序列化执行模式,其中函数在单个进程中按顺序 (FIFO) 顺序执行;这简化了函数调试,尽管其行为不同于云中函数的多进程、并行执行。
--export-on-exit=可选的。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器一起使用。指示模拟器在关机时将数据导出到目录,如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 for Firebase 模拟器一起使用。将使用--export-on-exit启动选项或emulators:export命令保存的数据导入到正在运行的身份验证、Cloud Firestore、实时数据库或 Cloud Storage for Firebase 模拟器实例。当前在模拟器内存​​中的任何数据都将被覆盖。
模拟器:执行scriptpath在为 firebase.json 中配置的firebase.json产品启动模拟器后,在scriptpath处运行脚本。脚本完成运行后,模拟器进程将自动停止。
旗帜说明
--only可选的。限制哪些模拟器启动。提供以逗号分隔的模拟器名称列表,指定“firestore”、“database”、“functions”、“hosting”或“pubsub”中的一个或多个。
--inspect-functions debug_port可选的。与 Cloud Functions 模拟器一起使用可在指定端口(或默认端口 9229,如果省略参数)启用函数的断点调试。请注意,当提供此标志时,Cloud Functions 模拟器会切换到特殊的序列化执行模式,其中函数在单个进程中按顺序 (FIFO) 顺序执行;这简化了函数调试,尽管其行为不同于云中函数的多进程、并行执行。
--export-on-exit=可选的。与 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器一起使用。指示模拟器在关机时将数据导出到目录,如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 for Firebase 模拟器一起使用。将使用--export-on-exit启动选项或emulators:export命令保存的数据导入到正在运行的身份验证、Cloud Firestore、实时数据库或 Cloud Storage for Firebase 模拟器实例。当前在模拟器内存​​中的任何数据都将被覆盖。
--ui可选的。在执行期间运行模拟器 UI。

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

导出和导入模拟器数据

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

模拟器:export export_directory

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

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

与您的 CI 系统集成

运行容器化的 Emulator Suite 映像

在典型 CI 设置中使用容器安装和配置 Emulator Suite 非常简单。

有几个问题需要注意:

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

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

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

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

要生成令牌,请在本地环境中运行firebase login:ci ;这不应该从 CI 系统执行。按照说明进行身份验证。您应该只需要在每个项目中执行一次此步骤,因为令牌将在构建中有效。令牌应被视为密码;确保它是保密的。

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

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

使用模拟器中心 REST API

列出正在运行的模拟器

要列出当前运行的模拟器,请将GET请求发送到 Emulator Hub 的/emulators端点。

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 或 Extensions 模拟器中运行的任何onDelete函数。

要暂时禁用本地函数触发器,请将PUT请求发送到 Emulator Hub 的/functions/disableBackgroundTriggers端点。

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

要在禁用本地函数触发器后启用它们,请将PUT请求发送到 Emulator Hub 的/functions/enableBackgroundTriggers端点。

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

模拟器 SDK 集成

本节中的表格指示客户端和管理 SDK 支持哪些模拟器。未来意味着模拟器支持已计划但尚不可用。

客户端 SDK 可用性

安卓苹果平台网络Firebase 界面
安卓
Firebase 界面
iOS
Firebase 界面
网络
实时数据库19.4.0 7.2.0 8.0.0 6.4.0未来不适用
云防火墙21.6.0 7.2.0 8.0.0 6.4.0未来不适用
验证20.0.0 7.0.0 8.0.0 7.0.0未来4.7.2
Firebase 的云存储20.0.0 8.0.0 8.4.0 7.0.0 11.0.0不适用
云函数19.1.0 7.2.0 8.0.0不适用不适用不适用
托管不适用不适用不适用不适用不适用不适用
扩展不适用不适用不适用不适用不适用不适用

管理 SDK 可用性

节点爪哇Python
实时数据库8.6.0 6.10.0 2.18.0未来
云防火墙8.0.0 6.10.0 3.0.0 1.0.0
验证9.3.0 7.2.0 5.0.0 4.2.0
Firebase 的云存储9.8.0未来未来未来
云函数不适用不适用不适用不适用
托管不适用不适用不适用不适用
扩展不适用不适用不适用不适用