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