擴充功能資訊清單是擴充功能執行個體及其設定的清單。透過資訊清單,您可以:
- 與他人共用擴充功能設定
- 在不同專案之間複製擴充功能設定 (例如從測試專案複製到實際工作環境專案)
- 一次部署所有擴充功能
- 使用 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
匯出專案的擴充功能設定
如要將專案目前的擴充功能設定儲存至資訊清單,請按照下列步驟操作:
- 如果尚未設定 Firebase CLI,請先完成這項操作。
- 在殼層提示中,切換至專案目錄。(您的專案目錄包含
firebase.json
檔案)。 - 執行
ext:export
指令:firebase ext:export
ext:export
指令會在 firebase.json
檔案中新增 extensions
區段。此外,ext:export
指令會建立一個 extensions
目錄,其中包含已安裝的每個擴充功能執行個體專屬的 .env
檔案。這些檔案包含每個執行個體的設定參數。
使用 Firebase 本機模擬器套件測試擴充功能設定
在擴充功能資訊清單中新增部分擴充功能執行個體後,您可以使用本機模擬器套件進行測試。
-
- 如要以互動方式執行模擬器套件,請執行:
firebase emulators:start
- 如要執行模擬器套件並執行測試指令碼,請執行:
firebase emulators:exec my-test.sh
- 如要以互動方式執行模擬器套件,請執行:
現在,如果您在資訊清單中列出擴充功能執行個體,本機模擬器套件就會將這些擴充功能的原始碼下載至 ~/.cache/firebase/extensions
。下載完畢後,本機模擬器套件將啟動,然後您就可以觸發擴充功能的任何背景觸發函式,並將應用程式連線至 Emulator 套件,測試這些套件與應用程式的整合情形。
將擴充功能設定部署至專案
將部分擴充功能執行個體新增至擴充功能資訊清單後,您可以使用 Firebase CLI 將其部署至專案。使用擴充功能資訊清單進行部署時,您可以一次安裝、更新並設定資訊清單中的所有擴充功能執行個體,然後一次在專案中。
如何部署擴充功能資訊清單:
- 在殼層提示中,變更為包含已儲存擴充功能設定的目錄。(這是包含
firebase.json
的目錄。如果您剛才執行ext:export
,您就已經在正確的目錄中。) - 請執行
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
中