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

您可以安裝及設定 Firebase 本機模擬器套件，用於不同的原型和測試環境，包括一次性原型設計工作階段，以及生產規模的持續整合工作流程。

安裝本機模擬器套件

安裝模擬器套件前，請先確認您具備下列項目：

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

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

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

   firebase --version

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

   firebase init

3. 設定模擬器套件。這個指令會啟動設定精靈，讓您選取感興趣的模擬器、下載對應的模擬器二進位檔，以及在預設通訊埠不適用的情況下設定模擬器通訊埠。

   firebase init emulators

安裝模擬器後，系統不會再檢查更新，也不會自動下載其他項目，直到您更新 Firebase CLI 版本為止。

設定模擬器套件

您也可以在 firebase.json 檔案中，設定模擬器的網路連接埠和安全規則定義的路徑：

• 執行 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 時，Local Emulator Suite 會發出警告，但您可以在 firebase.json 中將 singleProjectMode 鍵設為 false，藉此覆寫這項行為。

您可以在下列位置檢查專案 ID 聲明是否不符：

• 指令列中的預設專案。根據預設，啟動時系統會從以 firebase init 或 firebase use 選取的專案中取得專案 ID。如要查看專案清單 (並瞭解選取的專案)，請使用 firebase projects:list。
• 規則單元測試。專案 ID 通常會在呼叫規則單元測試程式庫方法 initializeTestEnvironment 或 initializeTestApp 時指定。
• 指令列 --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 系統

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

在一般 CI 設定中，使用容器安裝及設定 Emulator Suite 非常簡單。

請注意以下幾點：

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

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

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

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

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

如要產生權杖，請在本機環境中執行 firebase login:ci，請勿從 CI 系統執行這項操作。按照操作說明進行驗證。每個專案只需要執行一次這個步驟，因為權杖在各個建構版本中都有效。請將權杖視為密碼，務必嚴格保密。

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

最後，您也可以直接在建構指令碼中加入權杖，但請務必確保不受信任的第三方無法存取。如要採用這種硬式編碼方法，請將 --token "YOUR_TOKEN_STRING_HERE" 新增至 firebase emulators:exec 指令。

使用 Emulator Hub REST API

列出正在執行的模擬器

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

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 適用情形