使用 Extensions 資訊清單管理專案設定

擴充功能資訊清單是擴充功能執行個體及其設定的清單。透過資訊清單，您可以：

  • 與他人共用擴充功能設定
  • 在不同專案之間複製擴充功能設定 (例如從測試專案複製到實際工作環境專案)
  • 一次部署所有擴充功能
  • 使用 Firebase 本機模擬器套件，測試擴充功能如何與應用程式搭配運作
  • 將擴充功能設定修訂為原始碼控管
  • 在 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",
 }
}

  • 在 Firebase 專案目錄的 extensions/ 子目錄中，包含每個擴充功能執行個體設定的 .env 檔案。舉例來說，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. 在殼層提示中，切換至專案目錄。(您的專案目錄包含 firebase.json 檔案)。
  3. 執行 ext:export 指令：
    firebase ext:export

ext:export 指令會在 firebase.json 檔案中新增 extensions 區段。此外，ext:export 指令會建立一個 extensions 目錄，其中包含已安裝的每個擴充功能執行個體專屬的 .env 檔案。這些檔案包含每個執行個體的設定參數。

使用 Firebase 本機模擬器套件測試擴充功能設定

在擴充功能資訊清單中新增部分擴充功能執行個體後，您可以使用本機模擬器套件進行測試。

  1. 安裝及設定本機模擬器套件。

  2. 啟動本機模擬器套件：

    • 如要以互動方式執行模擬器套件，請執行：firebase emulators:start
    • 如要執行模擬器套件並執行測試指令碼，請執行：firebase emulators:exec my-test.sh

現在，如果您在資訊清單中列出擴充功能執行個體，本機模擬器套件就會將這些擴充功能的原始碼下載至 ~/.cache/firebase/extensions。下載完畢後，本機模擬器套件將啟動，然後您就可以觸發擴充功能的任何背景觸發函式，並將應用程式連線至 Emulator 套件，測試這些套件與應用程式的整合情形。

將擴充功能設定部署至專案

將部分擴充功能執行個體新增至擴充功能資訊清單後，您可以使用 Firebase CLI 將其部署至專案。使用擴充功能資訊清單進行部署時，您可以一次安裝、更新並設定資訊清單中的所有擴充功能執行個體，然後一次在專案中。

如何部署擴充功能資訊清單：

  1. 在殼層提示中，變更為包含已儲存擴充功能設定的目錄。(這是包含 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 中