安裝、配置和集成本地模擬器套件

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未來未來未來
雲功能不適用不適用不適用不適用
託管不適用不適用不適用不適用
擴展不適用不適用不適用不適用