安裝、配置和整合本地模擬器套件

Firebase 本機模擬器套件可以針對不同的原型和測試環境進行安裝和配置,從一次性原型設計會話到生產規模的持續整合工作流程。

安裝本地模擬器套件

在安裝模擬器套件之前,您需要:

  • Node.js版本 16.0 或更高版本。
  • Java JDK 版本 11 或更高版本。

要安裝模擬器套件:

  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 模擬器將以開放資料安全性運行。

命令描述
初始化模擬器啟動模擬器初始化精靈。確定要安裝的模擬器並可選擇指定模擬器連接埠設定。 init emulators是非破壞性的;接受預設值將保留目前的模擬器配置。

連接埠配置

每個模擬器都使用首選預設值綁定到電腦上的不同連接埠。

模擬器預設連接埠
驗證9099
模擬器套件使用者介面4000
雲端功能5001
事件弧9299
即時資料庫9000
雲端Firestore 8080
Firebase 雲端儲存9199
Firebase 託管5000
發布/訂閱8085

專案ID配置

根據您呼叫模擬器的方式,您可以使用不同的 Firebase 專案 ID 來運行模擬器的多個實例,也可以針對給定專案 ID 執行多個模擬器實例。在這種情況下,模擬器實例在單獨的環境中運作。

通常,為所有模擬器呼叫設定一個項目 ID 是一種很好的做法,這樣模擬器套件 UI、不同的產品模擬器以及特定模擬器的所有正在運行的實例都可以在所有情況下正確通訊。

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

您可以在以下位置檢查項目 ID 聲明是否不符:

  • 命令列中的預設項目。預設情況下,專案 ID 將在啟動時從使用firebase initfirebase use選擇的專案中取得。要查看項目清單(並查看選擇了哪一個),請使用firebase projects:list
  • 規則單元測試。項目 ID 通常在呼叫規則單元測試庫方法initializeTestEnvironmentinitializeTestApp時指定。
  • 命令列--project標誌。傳遞 Firebase CLI --project標誌會覆寫預設項目。您需要確保標誌的值與單元測試和應用程式初始化中的項目 ID 相符。

請同時檢查您在設定Apple 平台AndroidWeb專案時設定的特定於平台的專案 ID 配置。

安全規則配置

模擬器將從firebase.json中的databasefirestorestorage配置金鑰取得安全規則配置。

{
  // 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 選項

即時資料庫模擬器、Cloud Firestore 模擬器和 Cloud Storage for Firebase 模擬器的一部分是基於 Java,可以透過環境變數JAVA_TOOL_OPTIONS使用 JVM 標誌進行自訂。

例如,如果您遇到 Java 堆空間相關錯誤,您可以將最大 Java 堆大小增加到 4GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

可以在用空格分隔的引號中指定多個標誌,例如JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" 。這些標誌僅影響模擬器的基於 Java 的元件,對 Firebase CLI 的其他部分(例如模擬器套件 UI)沒有影響。

啟動模擬器

您可以啟動模擬器運行直至手動終止,或執行指定的測試腳本的持續時間,然後自動關閉。

命令描述
模擬器:啟動啟動firebase.json中配置的 Firebase 產品的模擬器。模擬器進程將繼續運行,直到明確停止為止。呼叫emulators:start會將模擬器下載到 ~/.cache/firebase/emulators/ (如果尚未安裝)。
旗幟描述
--only選修的。限制啟動哪些模擬器。提供以逗號分隔的模擬器名稱列表,指定「auth」、「database」、「firestore」、「functions」、「hosting」或「pubsub」中的一個或多個。
--inspect-functions debug_port選修的。與 Cloud Functions 模擬器結合使用,在指定連接埠(如果省略參數,則為預設連接埠 9229)啟用函數的斷點偵錯。請注意,提供此標誌時,Cloud Functions 模擬器會切換到特殊的序列化執行模式,在該模式中,函數會依序 (FIFO) 在單一進程中執行;這簡化了函數調試,儘管其行為與雲端中函數的多進程並行執行不同。
--export-on-exit=選修的。與身份驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器結合使用。指示模擬器在關閉時將資料匯出到目錄,如emulators:export指令所述。可以使用此標誌指定匯出目錄: firebase emulators:start --export-on-exit=./saved-data 。如果使用--import ,則導出路徑預設相同;例如: firebase emulators:start --import=./data-path --export-on-exit 。最後,如果需要,請將不同的目錄路徑傳遞給--import--export-on-exit標誌。
--import= import_directory選修的。與身份驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器結合使用。將使用--export-on-exit啟動選項或emulators:export指令儲存的資料匯入正在執行的驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器執行個體。當前仿真器記憶體中的任何資料都將被覆蓋。
模擬器:exec scriptpath啟動firebase.json中配置的 Firebase 產品的模擬器後,在scriptpath處執行腳本。腳本運行完畢後,模擬器進程將自動停止。
旗幟描述
--only選修的。限制啟動哪些模擬器。提供以逗號分隔的模擬器名稱列表,指定「firestore」、「database」、「functions」、「hosting」或「pubsub」中的一個或多個。
--inspect-functions debug_port選修的。與 Cloud Functions 模擬器結合使用,在指定連接埠(如果省略參數,則為預設連接埠 9229)啟用函數的斷點偵錯。請注意,提供此標誌時,Cloud Functions 模擬器會切換到特殊的序列化執行模式,在該模式中,函數會依序 (FIFO) 在單一進程中執行;這簡化了函數調試,儘管其行為與雲端中函數的多進程並行執行不同。
--export-on-exit=選修的。與身份驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器結合使用。指示模擬器在關閉時將資料匯出到目錄,如emulators:export指令所述。可以使用此標誌指定匯出目錄: firebase emulators:start --export-on-exit=./saved-data 。如果使用--import ,則導出路徑預設相同;例如: firebase emulators:start --import=./data-path --export-on-exit 。最後,如果需要,請將不同的目錄路徑傳遞給--import--export-on-exit標誌。
--import= import_directory選修的。與身份驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器結合使用。將使用--export-on-exit啟動選項或emulators:export指令儲存的資料匯入正在執行的驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器執行個體。當前模擬器記憶體中的所有資料都將被覆蓋。
--ui選修的。在執行期間運行模擬器 UI。

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

匯出和導入模擬器數據

您可以從 Authentication、Cloud Firestore、Realtime Database 和 Cloud Storage for Firebase 模擬器中匯出數據,以用作可共享的通用基準數據集。如上所述,可以使用--import標誌匯入這些資料集。

模擬器:匯出export_directory

身份驗證、Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器。從正在執行的 Cloud Firestore、即時資料庫或 Cloud Storage for Firebase 模擬器實例匯出資料。如果指定的export_directory尚不存在,則將建立該目錄。如果指定的目錄存在,系統會提示您確認是否覆寫先前的匯出資料。您可以使用--force標誌跳過此提示。匯出目錄包含資料清單檔案firebase-export-metadata.json

您可以使用上述--export-on-exit標誌指示模擬器在關閉時自動匯出資料。

與您的 CI 系統集成

運行容器化模擬器套件鏡像

在典型 CI 設定中使用容器安裝和設定模擬器套件非常簡單。

有幾個問題要注意:

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

    • 您可能希望將此路徑新增至 CI 快取配置中以避免重複下載。
  • 如果儲存庫中沒有firebase.json文件,則必須向emulators:startemulators:exec命令新增命令列參數以指定應啟動哪些模擬器。例如,
    --only functions,firestore

產生身份驗證令牌(僅限託管模擬器)

如果您的持續整合工作流程依賴 Firebase Hosting ,那麼您將需要使用令牌登入才能執行firebase emulators:exec 。其他模擬器不需要登入。

要產生令牌,請在本地環境中運行firebase login:ci ;這不應該從 CI 系統執行。按照說明進行身份驗證。您應該只需要為每個專案執行一次此步驟,因為令牌在各個建置中都有效。令牌應該像密碼一樣對待;確保其保密。

如果您的 CI 環境允許您指定可在建置腳本中使用的環境變量,只需建立名為FIREBASE_TOKEN的環境變量,其值為存取令牌字串。 Firebase CLI 將自動取得FIREBASE_TOKEN環境變量,並且模擬器將正確啟動。

作為最後的手段,您可以簡單地將令牌包含在建置腳本中,但請確保不受信任的各方無權存取。對於這種硬編碼方法,您可以將--token "YOUR_TOKEN_STRING_HERE"新增至firebase emulators:exec命令。

使用模擬器中心 REST API

列出正在運行的模擬器

若要列出目前正在執行的模擬器,請將GET請求傳送到模擬器中心的/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請求傳送到模擬器中心的/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 集成

本節中的表格指示客戶端和管理 SDK 支援哪些模擬器。未來意味著模擬器支援已計劃但尚未提供。

客戶端 SDK 可用性

安卓蘋果平台網路Firebase 使用者介面
安卓
Firebase 使用者介面
iOS系統
Firebase 使用者介面
網路
即時資料庫19.4.0 7.2.0 8.0.0 6.4.0未來不適用
雲端Firestore 21.6.0 7.2.0 8.0.0 6.4.0未來不適用
驗證20.0.0 7.0.0 8.0.0 7.0.0未來4.7.2
Firebase 雲端儲存20.0.0 8.0.0 8.4.0 7.0.0 11.0.0不適用
雲端功能19.1.0 7.2.0 8.0.0不適用不適用不適用
託管不適用不適用不適用不適用不適用不適用
擴充不適用不適用不適用不適用不適用不適用

管理 SDK 可用性

節點爪哇Python
即時資料庫8.6.0 6.10.0 2.18.0未來
雲端Firestore 8.0.0 6.10.0 3.0.0 1.0.0
驗證9.3.0 7.2.0 5.0.0 4.2.0
Firebase 雲端儲存9.8.0未來未來未來
雲端功能不適用不適用不適用不適用
託管不適用不適用不適用不適用
擴充不適用不適用不適用不適用