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

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

  • 与他人共享您的扩展程序配置
  • 在不同项目之间复制扩展程序配置(例如从预演项目复制到生产项目)
  • 一次部署所有扩展程序
  • 使用 Firebase Local Emulator Suite 测试您的扩展程序如何与您的应用搭配使用
  • 将扩展程序配置提交到源代码控制系统
  • 在 CI/CD 流水线中添加扩展程序

扩展程序清单包含两个部分:

  • firebase.jsonextensions 部分,是实例 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