获取我们在 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、Realtime Database 和 Cloud Storage for Firebase 模拟器将以开放数据安全方式运行。

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

端口配置

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

模拟器默认端口
验证9099
模拟器套件用户界面4000
云端功能5001
事件弧9299
实时数据库9000
云端 Firestore 8080
用于 Firebase 的云存储9199
火力地堡托管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 platformsAndroidweb项目时设置的特定于平台的项目 ID 配置。

安全规则配置

模拟器将从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": {
    "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=选修的。与身份验证、Cloud Firestore、实时数据库或 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选修的。与身份验证、Cloud Firestore、实时数据库或 Cloud Storage for Firebase 模拟器一起使用。将使用--export-on-exit启动选项或emulators:export命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 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=选修的。与身份验证、Cloud Firestore、实时数据库或 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选修的。与身份验证、Cloud Firestore、实时数据库或 Cloud Storage for Firebase 模拟器一起使用。将使用--export-on-exit启动选项或emulators:export命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器实例。当前在模拟器内存​​中的任何数据都将被覆盖。
--ui选修的。在执行期间运行 Emulator UI。

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

导出和导入模拟器数据

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

模拟器:导出export_directory

身份验证、Cloud Firestore、Realtime Database 或 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

列出正在运行的模拟器

要列出当前正在运行的模拟器,请向模拟器中心的/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 或 Extensions 模拟器中运行的任何onDelete函数。

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

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

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

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

模拟器 SDK 集成

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

客户端 SDK 可用性

安卓苹果平台网络火力地堡用户界面
安卓
火力地堡用户界面
iOS
火力地堡用户界面
网络
实时数据库19.4.0 7.2.0 8.0.0 6.4.0未来不适用
云端 Firestore 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未来
云端 Firestore 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未来未来未来
云端功能不适用不适用不适用不适用
托管不适用不适用不适用不适用
扩展不适用不适用不适用不适用