Catch up on highlights from Firebase at Google I/O 2023. Learn more

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

可以為不同的原型和測試環境安裝和配置 Firebase Local Emulator Suite,從一次性原型製作會話到生產規模的持續集成工作流。

安裝本地模擬器套件

在安裝 Emulator Suite 之前,您需要:

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

要安裝模擬器套件:

  1. 安裝Firebase CLI 。如果您尚未安裝 Firebase CLI,請立即安裝。您需要 CLI 版本 8.14.0 或更高版本才能使用 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 模擬器將以開放數據安全方式運行。

命令描述
初始化模擬器啟動模擬器初始化嚮導。確定要安裝的仿真器並可選擇指定仿真器端口設置。 init emulators是非破壞性的;接受默認值將保留當前的模擬器配置。

端口配置

每個模擬器都使用首選默認值綁定到您計算機上的不同端口。

模擬器默認端口
驗證9099
模擬器套件用戶界面4000
雲端功能5001
事件弧9299
實時數據庫9000
雲端 Firestore 8080
用於 Firebase 的雲存儲9199
火力地堡託管5000
發布/訂閱8085

項目ID配置

根據您調用模擬器的方式,您可以使用不同的 Firebase 項目 ID 運行一個模擬器的多個實例,或者為一個給定的項目 ID 運行多個模擬器實例。在這種情況下,模擬器實例在單獨的環境中運行。

為所有模擬器調用設置一個項目 ID 通常是一種很好的做法,這樣 Emulator Suite 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 platformsAndroidweb項目時設置的特定於平台的項目 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 的其他部分沒有影響,例如 Emulator Suite 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命令保存的數據導入正在運行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模擬器實例。當前在模擬器內存中的任何數據都將被覆蓋。
模擬器:執行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命令保存的數據導入正在運行的 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模擬器實例。當前在模擬器內存中的任何數據都將被覆蓋。
--ui選修的。在執行期間運行 Emulator UI。

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

導出和導入模擬器數據

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

模擬器:導出export_directory

身份驗證、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模擬器。從正在運行的 Cloud Firestore、實時數據庫或 Cloud Storage for Firebase 模擬器實例中導出數據。如果指定的export_directory不存在,將創建它。如果指定的目錄存在,系統會提示您確認是否覆蓋之前導出的數據。您可以使用--force標誌跳過此提示。導出目錄包含一個數據清單文件firebase-export-metadata.json

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

與您的 CI 系統集成

運行容器化的 Emulator Suite 圖像

在典型的 CI 設置中使用容器安裝和配置 Emulator Suite 非常簡單。

有幾個問題需要注意:

  • 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

列出正在運行的模擬器

要列出當前正在運行的模擬器,請向模擬器中心的/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請求發送到模擬器中心的/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 可用性

安卓蘋果平台網絡火力地堡用戶界面
安卓
火力地堡用戶界面
iOS
火力地堡用戶界面
網絡
實時數據庫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未來未來未來
雲端功能不適用不適用不適用不適用
託管不適用不適用不適用不適用
擴展不適用不適用不適用不適用