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

擴充功能資訊清單是擴充功能例項及其設定的清單。您可以透過資訊清單執行下列操作：

  • 與他人分享擴充功能設定
  • 在不同專案之間複製擴充功能設定 (例如從測試專案複製到正式專案)
  • 一次部署所有擴充功能
  • 使用 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}.firebasestorage.app
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 Local Emulator Suite 測試擴充功能設定

在擴充功能資訊清單中新增一些擴充功能執行個體後，您可以使用 Local Emulator Suite 進行測試。

  1. 安裝及設定 Local Emulator Suite。

  2. 啟動 Local Emulator Suite：

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

現在，如果您在資訊清單中列出擴充功能例項，Local Emulator Suite 就會將這些擴充功能的原始碼下載到 ~/.cache/firebase/extensions。下載完成後，Local Emulator Suite 就會啟動，您就能觸發任何擴充功能的背景觸發函式，並將應用程式連結至模擬器套件，測試擴充功能與應用程式的整合情形。

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

將一些擴充功能例項新增至擴充功能資訊清單後，您可以使用 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