使用扩展程序清单管理项目配置

扩展程序清单是扩展程序实例及其配置的列表。借助该清单，您可以：

  • 与他人共享您的扩展程序配置
  • 在不同项目之间复制扩展程序配置（例如从预演项目复制到生产项目）
  • 一次部署所有扩展程序
  • 使用 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

导出项目的扩展程序配置

如需将项目的当前扩展程序配置保存到清单，请执行以下操作：

  1. 如果您尚未设置 Firebase CLI，请执行此操作
  2. 从 shell 提示符处切换到项目目录（您的项目目录包含 firebase.json 文件）。
  3. 运行 ext:export 命令： 
    firebase ext:export

ext:export 命令会将 extensions 部分添加到 firebase.json 文件中。此外，ext:export 命令还会创建一个 extensions 目录，其中包含您已安装的每个扩展程序实例的 .env 文件。这些文件包含每个实例的配置参数。

使用 Firebase Local Emulator Suite 测试扩展程序配置

将一些扩展程序实例添加到扩展程序清单后，您可以使用 Local Emulator Suite 对其进行测试。

  1. 安装和配置 Local Emulator Suite。

  2. 启动 Local Emulator Suite：

    • 如需以交互方式运行 Emulator Suite，请运行以下命令：firebase emulators:start
    • 如需运行 Emulator Suite 并执行测试脚本，请运行以下命令：firebase emulators:exec my-test.sh

现在，如果您的清单中列出了扩展程序实例，则 Local Emulator Suite 会将这些扩展程序的源代码下载到 ~/.cache/firebase/extensions。下载完成后，系统将启动 Local Emulator Suite，然后您将能够触发扩展程序的任何后台触发函数，并将您的应用连接到 Emulator Suite 以测试这些函数与应用的集成。

将扩展程序配置部署到项目

将一些扩展程序实例添加到扩展程序清单后，您可以使用 Firebase CLI 将其部署到项目。使用扩展程序清单进行部署时，您可以一次性在项目中安装、更新和配置清单中的所有扩展程序实例。

如需部署扩展程序清单，请执行以下操作：

  1. 从 shell 提示符中，切换到包含已保存的扩展程序配置的目录（这是包含 firebase.json 的目录。如果您刚刚运行了 ext:export，那么您已经位于正确的目录）。
  2. 运行 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 中