安装、配置和集成 Local Emulator Suite

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

安装 Local Emulator Suite

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

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

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

安装 Firebase CLI。如果您尚未安装 Firebase CLI，请立即安装。您需要安装 CLI 8.14.0 或更高版本才能使用 Emulator Suite。可以使用以下命令检查已安装的版本：
```
firebase --version
```
将当前工作目录初始化为 Firebase 项目，并按照屏幕上的提示指定要使用的产品（如果您尚未执行此操作）：
```
firebase init
```
设置 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 模拟器将在开放的数据安全机制下运行。

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

端口配置

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

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

项目 ID 配置

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

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

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 界面）没有影响。

启动模拟器

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

命令说明

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 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` 命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器实例。当前存储在模拟器内存中的任何数据都将被覆盖。

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 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` 命令保存的数据导入正在运行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器实例。当前存储在模拟器内存中的任何数据都将被覆盖。
`--ui`	可选。在执行期间运行模拟器界面。

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

导出和导入模拟器数据

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

emulators:export export_directory

Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模拟器。从正在运行的 Cloud Firestore、Realtime Database 或 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: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 可用性

	Android	Apple 平台	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	未来	4.7.2
Cloud Storage for Firebase	20.0.0	8.0.0	8.4.0	7.0.0	11.0.0	不适用
Cloud Functions	19.1.0	7.2.0	8.0.0	不适用	不适用	不适用
Hosting	不适用	不适用	不适用	不适用	不适用	不适用
Extensions	不适用	不适用	不适用	不适用	不适用	不适用

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	7.2.0	5.0.0	4.2.0
Cloud Storage for Firebase	9.8.0	未来	未来	未来
Cloud Functions	不适用	不适用	不适用	不适用
Hosting	不适用	不适用	不适用	不适用
Extensions	不适用	不适用	不适用	不适用