扩展清单是扩展实例及其配置的列表。使用清单,您可以:
- 与他人分享您的扩展配置
- 在不同项目之间复制您的扩展配置(例如从您的暂存项目到您的生产项目)
- 一次部署所有扩展
- 使用 Firebase Local Emulator Suite 测试您的扩展程序如何与您的应用协同工作
- 将您的扩展配置提交到源代码管理
- 在 CI/CD 管道中包含扩展
扩展清单有两部分:
firebase.json
的extensions
部分,它是实例 ID 到扩展版本参考的映射。例如:{ "extensions": { "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18", "my-image-resizer": "firebase/storage-resize-images@^0.1.22", } }
包含每个扩展实例配置的
.env
文件,位于 Firebase 项目目录的extensions/
子目录中。例如,storage-resize-images
的一个实例可能有一个如下所示的.env
文件:IMAGE_TYPE=jpeg LOCATION=us-central1 IMG_BUCKET=${param:PROJECT_ID}.appspot.com IMG_SIZES=100x100 DELETE_ORIGINAL_FILE=false
创建扩展清单
可以通过三种方式构建扩展清单:
- 使用 Firebase CLI 管理您的扩展程序清单
- 导出项目的扩展配置
- 手动编辑清单文件
下面解释前两种方法。
使用 Firebase CLI 管理您的扩展程序清单
您可以使用--local
选项运行大多数 Firebase CLI 的ext:
命令来更新扩展清单,而无需实际更改项目的当前配置。
例如:
firebase ext:install --local firebase/firestore-bigquery-export
运行上述命令将提示您配置最新版本的firebase/firestore-bigquery-export
扩展并将配置保存到清单中,但不会将配置部署到您的项目中。
以下是修改扩展清单的命令的更多示例:
# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local
# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local
# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local
# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local
导出项目的扩展配置
要将项目的当前扩展配置保存到清单,请执行以下操作:
- 如果您还没有这样做,请设置 Firebase CLI
- 在 shell 提示符下,切换到项目目录。 (您的项目目录包含文件
firebase.json
)。 - 运行
ext:export
命令:firebase ext:export
ext:export
命令将向firebase.json
文件添加一个extensions
部分。此外, ext:export
命令会为您安装的每个扩展实例创建一个包含.env
文件的extensions
目录。这些文件包含每个实例的配置参数。
使用 Firebase Local Emulator Suite 测试扩展配置
将一些扩展实例添加到扩展清单后,您可以使用 Local Emulator Suite 测试它们。
- 要以交互方式运行 Emulator Suite,请运行:
firebase emulators:start
- 要运行 Emulator Suite 并执行测试脚本,请运行:
firebase emulators:exec my-test.sh
- 要以交互方式运行 Emulator Suite,请运行:
现在,如果您的清单中列出了扩展实例,Local Emulator Suite 会将这些扩展的源代码下载到~/.cache/firebase/extensions
。下载后,本地模拟器套件将启动,您将能够触发任何扩展程序的后台触发功能,并将您的应用程序连接到模拟器套件以测试它们与您的应用程序的集成。
将扩展配置部署到项目
将一些扩展实例添加到扩展清单后,您可以使用 Firebase CLI 将其部署到项目中。当您使用扩展清单进行部署时,您可以一次性将清单中的所有扩展实例安装、更新和配置到一个项目中。
要部署扩展清单:
- 在 shell 提示符下,切换到包含保存的扩展配置的目录。 (这是包含
firebase.json
的目录。如果您刚刚运行ext:export
,那么您已经在正确的目录中。) - 运行
deploy
命令。如果要将扩展部署到当前项目以外的项目,还要指定--project=
:firebase deploy --only extensions –-project=YOUR_PROJECT_ID
deploy
命令将验证每个实例配置,询问您是否要从目标项目中删除firebase.json
中未列出的任何扩展实例,然后部署所有扩展实例。
项目特定的扩展配置
保存的扩展配置可用于部署到多个不同的项目:例如,一个暂存项目和一个生产项目。执行此操作时,每个项目的某些参数值可能需要不同。项目特定的.env
文件使这成为可能:
- 将项目之间不同的参数值放在
extensions/ EXTENSION_INSTANCE_ID .env. YOUR_PROJECT_ID
- 将共享参数值放在
extensions/ EXTENSION_INSTANCE_ID .env
中。
有时,您可能希望在模拟扩展时使用不同的参数值:例如,您可能希望提供测试 API 密钥而不是生产密钥。将这些参数放在.local
文件中:
- 在
extensions/ EXTENSION_INSTANCE_ID .env.local
中放置您想在仿真期间使用的非秘密参数 - 将秘密参数值放入
extensions/ EXTENSION_INSTANCE_ID .secret.local