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

您可以安裝 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 檔案中，設定模擬器的網路通訊埠和安全性規則定義的路徑：

• 如要變更模擬器通訊埠，請執行 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 系統

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

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

請注意以下幾點：

• 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 環境變數，模擬器也會正常啟動。

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

使用 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 要求至 Emulator Hub 的 /functions/enableBackgroundTriggers 端點。

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

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

{
  "enabled": true
}

模擬器 SDK 整合

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

用戶端 SDK 適用情形

Admin SDK 適用情形