安装、配置和集成 Local Emulator Suite

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

安装 Local Emulator Suite

在安装 Emulator Suite 之前，您需要安装以下软件：

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

如需安装 Emulator Suite，请执行以下操作：

1. 安装 Firebase CLI。 如果您尚未安装 Firebase CLI，请立即安装。您需要安装 CLI 8.14.0 或更高版本才能使用 Emulator Suite。可以使用以下命令检查已安装的版本：

   firebase --version

2. 将当前工作目录初始化为 Firebase 项目，并按照屏幕上的提示指定要使用的产品（如果您尚未执行此操作）：

   firebase init

3. 设置 Emulator Suite。此命令会启动配置向导，让您选择所需的模拟器，下载相应的模拟器二进制文件，以及在默认设置不合适时设置模拟器端口。

   firebase init emulators

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

配置 Emulator Suite

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

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

如果您不配置这些设置，模拟器将监听其默认端口，并且 Cloud Firestore、Realtime Database 和 Cloud Storage for Firebase 模拟器将在开放的数据安全机制下运行。

端口配置

每个模拟器都会绑定到机器上的不同端口，每个端口都有一个首选默认值。

项目 ID 配置

您可以根据调用模拟器的方式，使用不同的 Firebase 项目 ID 运行模拟器的多个实例，或者为某个项目 ID 运行多个模拟器实例。在这些情况下，模拟器实例会在单独的环境中运行。

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

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

您可在以下位置检查项目 ID 声明是否存在不一致的现象：

• 命令行中的默认项目。默认情况下，模拟器会在启动时从使用 firebase init 或 firebase use 选择的项目中获取项目 ID。如需查看项目列表（以及查看已选择的项目），请使用 firebase projects:list。
• 规则单元测试。项目 ID 通常在对规则单元测试库方法 initializeTestEnvironment 或 initializeTestApp 的调用中指定。
• 命令行 --project 标志。传递 Firebase CLI --project 标志会替换默认项目。您需要确保该标志的值与单元测试和应用初始化中的项目 ID 一致。

此外，您还要检查在配置 Apple 平台、Android 和 Web 项目时选择的特定于平台的项目 ID。

安全规则配置

模拟器将通过 firebase.json 中的 database、firestore 和 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 选项

Realtime Database 模拟器、Cloud Firestore 模拟器以及 Cloud Storage for Firebase 模拟器的一部分都基于 Java，您可以使用环境变量 JAVA_TOOL_OPTIONS 通过 JVM 标志对其进行自定义。

例如，如果您遇到与 Java 堆空间相关的错误，可以将 Java 堆大小的上限增加到 4 GB：

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

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

启动模拟器

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

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

导出和导入模拟器数据

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

与 CI 系统集成

运行容器化的 Emulator Suite 映像

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

您需要注意以下几个问题：

• JAR 文件安装在 ~/.cache/firebase/emulators/ 中并在该目录下缓存。

  • 您可能需要将此路径添加到 CI 缓存配置，以免重复下载。

• 如果您的代码库中没有 firebase.json 文件，则必须向 emulators:start 或 emulators:exec 命令添加命令行参数，以指定应启动的模拟器。例如，
  --only functions,firestore。

生成身份验证令牌（仅限 Hosting 模拟器）

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

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

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

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

使用 Emulator Hub 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 函数。

要暂时停用本地函数触发器，请向模拟器中心的 /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 可用性

Admin SDK 可用性