使用 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：

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

現在，如果資訊清單中列有擴充功能執行個體，Local Emulator Suite 會將這些擴充功能的原始碼下載到 ~/.cache/firebase/extensions。下載完成後，Local Emulator Suite 就會啟動，您將能觸發任何擴充功能的背景觸發函式，並將應用程式連結至 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 金鑰，而非正式版 API 金鑰。將這些參數放入 .local 檔案：

  • 將要在模擬期間使用的非機密參數放入 extensions/EXTENSION_INSTANCE_ID.env.local
  • 將密鑰參數值放入 extensions/EXTENSION_INSTANCE_ID.secret.local