扩展程序清单是扩展程序实例及其配置的列表。借助该清单,您可以:
- 与他人共享您的扩展程序配置
- 在不同项目之间复制扩展程序配置(例如从预演项目复制到生产项目)
- 一次部署所有扩展程序
- 使用 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
命令会将 extensions
部分添加到 firebase.json
文件中。此外,ext:export
命令还会创建一个 extensions
目录,其中包含您已安装的每个扩展程序实例的 .env
文件。这些文件包含每个实例的配置参数。
使用 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
。下载完成后,系统将启动 Local Emulator Suite,然后您将能够触发扩展程序的任何后台触发函数,并将您的应用连接到 Emulator Suite 以测试这些函数与应用的集成。
将扩展程序配置部署到项目
将一些扩展程序实例添加到扩展程序清单后,您可以使用 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
中