安裝、設定及整合本機模擬器套件

Firebase 本機模擬器套件可針對各種原型和測試環境進行安裝和設定，包括一次性原型建立工作階段，以及實際規模的持續整合工作流程。

安裝本機模擬器套件

安裝模擬器套件前，您需要：

• Node.js 16.0 以上版本。
• Java JDK 第 11 版以上版本。

如要安裝 Emulator Suite，請按照下列步驟操作：

1. 安裝 Firebase CLI。如果您尚未安裝 Firebase CLI，請立即安裝。 您必須使用 CLI 8.14.0 以上版本，才能使用模擬器套件。您可以使用下列指令查看已安裝的版本：

   firebase --version

2. 如果您尚未將目前的工作目錄初始化為 Firebase 專案，請按照畫面上的提示指定要使用的產品：

   firebase init

3. 設定模擬器套件。這個指令會啟動設定精靈，讓您選取所需的模擬器、下載對應的模擬器二進位檔案，以及在預設值不合適時設定模擬器通訊埠。

   firebase init emulators

安裝模擬器後，系統不會執行更新檢查，也不會在您更新 Firebase CLI 版本前，自動下載其他內容。

設定模擬器套件

您可以選擇在 firebase.json 檔案中設定模擬器的網路連接埠和 SecurityRules 定義路徑：

• 執行 firebase init emulators 或手動編輯 firebase.json，變更模擬器連接埠。
• 手動編輯 firebase.json，即可變更安全性規則定義的路徑。

如果您未設定這些設定，模擬器會在預設連接埠上聆聽，而 Cloud Firestore、Realtime Database 和 Cloud Storage for Firebase 模擬器會以開放式資料安全性執行。

通訊埠設定

每個模擬器都會綁定機器上的不同通訊埠，並使用偏好的預設值。

專案 ID 設定

視您叫用模擬器的方式而定，您可以使用不同的 Firebase 專案 ID，或針對特定專案 ID 執行多個模擬器執行個體，執行模擬器的多個執行個體。在這種情況下，模擬器執行個體會在個別環境中執行。

一般來說，建議您為所有模擬器叫用設定一個專案 ID，讓 Emulator Suite UI、不同的產品模擬器，以及特定模擬器執行的所有執行個體都能在所有情況下正確通訊。

Local Emulator Suite 會在環境中偵測到多個專案 ID 時發出警告，但您可以透過在 firebase.json 中將 singleProjectMode 鍵設為 false 來覆寫這項行為。

您可以檢查專案 ID 宣告是否有以下不相符之處：

• 指令列中的預設專案。根據預設，系統會在啟動時從使用 firebase init 或 firebase use 選取的專案取得專案 ID。如要查看專案清單 (並查看已選取哪個專案)，請使用 firebase projects:list。
• 規則單元測試。在呼叫規則單元測試程式庫方法 initializeTestEnvironment 或 initializeTestApp 時，通常會指定專案 ID。
• 指令列 --project 旗標。傳遞 Firebase CLI --project 標記會覆寫預設專案。您必須確保標記的值與單元測試和應用程式初始化的專案 ID 相符。

另外，請檢查您在設定 Apple 平台、Android 和 網頁 專案時所設定的平台專案 ID 設定。

安全性規則設定

模擬器會從 firebase.json 中的 database、firestore 和 storage 設定鍵取得安全性規則設定。

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

指定 Java 選項

Realtime Database 模擬器、Cloud Firestore 模擬器和部分 Cloud Storage for Firebase 模擬器是以 Java 為基礎，可透過環境變數 JAVA_TOOL_OPTIONS 使用 JVM 旗標進行自訂。

舉例來說，如果您遇到 Java 堆積空間相關錯誤，可以將 Java 堆積大小上限增加到 4 GB：

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

您可以使用引號指定多個旗標，並以空格分隔，例如 JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g"。標記只會影響模擬器的 Java 基礎元件，不會影響 Firebase CLI 的其他部分，例如 Emulator Suite UI。

啟動模擬器

您可以啟動模擬器，讓模擬器執行至手動終止為止，或讓模擬器執行指定測試指令碼的時間長度，然後自動關閉。

firebase emulators:exec 方法通常更適合持續整合工作流程。

匯出及匯入模擬器資料

您可以從 Authentication、Cloud Firestore、Realtime Database 和 Cloud Storage for Firebase 模擬器匯出資料，用於共用常用的基準資料集。您可以使用 --import 標記匯入這些資料集，如上文所述。

與持續整合系統整合

執行容器化模擬器套件映像檔

在一般 CI 設定中，使用容器安裝及設定模擬器套件相當簡單。

請注意以下幾個問題：

• JAR 檔案會在 ~/.cache/firebase/emulators/ 中安裝及快取。

  • 建議您將這個路徑新增至 CI 快取設定，以免重複下載。

• 如果存放區中沒有 firebase.json 檔案，您必須在 emulators:start 或 emulators:exec 指令中新增指令列引數，以指定要啟動哪一個模擬器。例如：
  --only functions,firestore。

產生驗證權杖 (僅限代管模擬器)

如果您的持續整合工作流程仰賴 Firebase Hosting，則您必須使用權杖登入，才能執行 firebase emulators:exec。其他模擬器則不需要登入。

如要產生權杖，請在本機環境執行 firebase login:ci，這不應從持續整合系統執行。按照操作說明進行驗證。您只需要為每個專案執行這項操作一次，因為權杖會在各個版本中有效。憑證應視為密碼；請務必妥善保管。

如果 CI 環境允許您指定可在建構指令碼中使用的環境變數，只要建立名為 FIREBASE_TOKEN 的環境變數，並將存取權存證字串設為值即可。Firebase CLI 會自動挑選 FIREBASE_TOKEN 環境變數，並正確啟動模擬器。

如非萬不得已，您可以直接在建構指令碼中加入權杖，但請確保未受信任的對象無法存取。對於這種硬式編碼方法，您可以將 --token "YOUR_TOKEN_STRING_HERE" 新增至 firebase emulators:exec 指令。

使用 Emulator Hub REST API

列出執行中的模擬器

如要列出目前執行中的模擬器，請將 GET 要求傳送至 Emulator Hub 的 /emulators 端點。

curl localhost:4400/emulators

結果會是 JSON 物件，列出所有執行中的模擬器及其主機/連接埠設定，例如：

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

啟用 / 停用背景函式觸發條件

在某些情況下，您需要暫時停用本機函式和擴充功能觸發事件。舉例來說，您可能想刪除 Cloud Firestore 模擬器中的所有資料，但不觸發在 Cloud Functions 或 Extensions 模擬器中執行的任何 onDelete 函式。

如要暫時停用本機函式觸發事件，請將 PUT 要求傳送至 Emulator Hub 的 /functions/disableBackgroundTriggers 端點。

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

結果會是 JSON 物件，其中詳細說明目前狀態。

{
  "enabled": false
}

如要在停用本機函式觸發事件後啟用，請將 PUT 要求傳送至模擬器中心的 /functions/enableBackgroundTriggers 端點。

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

結果會是 JSON 物件，其中詳細說明目前狀態。

{
  "enabled": true
}

模擬器 SDK 整合

本節中的表格會指出用戶端和 Admin SDK 支援的模擬器。「未來」表示模擬器支援功能已在規劃中，但尚未推出。

用戶端 SDK 可用性

Admin SDK 可用性