可以为不同的原型和测试环境安装和配置 Firebase Local Emulator Suite,从一次性原型制作会话到生产规模的持续集成工作流。
安装本地模拟器套件
在安装 Emulator Suite 之前,您需要:
要安装模拟器套件:
- 安装Firebase CLI 。如果您尚未安装 Firebase CLI,请立即安装。您需要 CLI 版本 8.14.0 或更高版本才能使用 Emulator Suite。您可以使用以下命令检查安装的版本:
firebase --version
- 如果您还没有这样做,请将当前工作目录初始化为 Firebase 项目,按照屏幕提示指定要使用的产品:
firebase init
- 设置模拟器套件。此命令会启动一个配置向导,让您可以选择感兴趣的仿真器、下载相应的仿真器二进制文件,并在默认值不合适时设置仿真器端口。
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 init
或firebase use
选择的项目中获取。要查看项目列表(并查看选择了哪个),请使用firebase projects:list
。 - 规则单元测试。项目 ID 通常在对规则单元测试库方法
initializeTestEnvironment
或initializeTestApp
的调用中指定。 - 命令行
--project
标志。传递 Firebase CLI--project
标志会覆盖默认项目。您需要确保标志的值与单元测试和应用程序初始化中的项目 ID 匹配。
还要检查您在配置Apple platforms 、 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 选项
实时数据库模拟器、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/(如果尚未安装)。
| ||||||||||||
模拟器:执行scriptpath | 为在 firebase.json 中配置的firebase.json 产品启动模拟器后,在scriptpath 运行脚本。当脚本完成运行时,模拟器进程将自动停止。
|
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 模拟器实例中导出数据。如果指定的 您可以使用上述 |
与您的 CI 系统集成
运行容器化的 Emulator Suite 图像
在典型的 CI 设置中使用容器安装和配置 Emulator Suite 非常简单。
有几个问题需要注意:
JAR 文件安装并缓存在
~/.cache/firebase/emulators/
。- 您可能希望将此路径添加到 CI 缓存配置中以避免重复下载。
如果您的存储库中没有
firebase.json
文件,则必须将命令行参数添加到emulators:start
或emulators: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 | 未来 | 未来 | 未来 |
云端功能 | 不适用 | 不适用 | 不适用 | 不适用 |
托管 | 不适用 | 不适用 | 不适用 | 不适用 |
扩展 | 不适用 | 不适用 | 不适用 | 不适用 |