Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

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

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

安裝本地模擬器套件

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

  • Node.js版本 8.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、實時數據庫和 Cloud Storage for Firebase 模擬器將在開放數據安全的情況下運行。

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

端口配置

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

模擬器默認端口
驗證9099
模擬器套件用戶界面4000
雲函數5001
事件弧9299
實時數據庫9000
雲防火牆8080
Firebase 的雲存儲9199
Firebase 託管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 平台AndroidWeb項目時設置的特定於平台的項目 ID 配置。

安全規則配置

模擬器將從databasefirestorefirebase.json中的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 選項

實時數據庫模擬器、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.json產品啟動模擬器。模擬器進程將繼續運行,直到明確停止。調用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=可選的。與 Authentication、Cloud Firestore、Realtime Database 或 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可選的。與 Authentication、Cloud Firestore、Realtime Database 或 Cloud Storage for Firebase 模擬器一起使用。將使用--export-on-exit啟動選項或emulators:export命令保存的數據導入到正在運行的身份驗證、Cloud Firestore、實時數據庫或 Cloud Storage for Firebase 模擬器實例。當前在模擬器內存中的任何數據都將被覆蓋。
模擬器:執行scriptpath在為 firebase.json 中配置的firebase.json產品啟動模擬器後,在scriptpath處運行腳本。腳本完成運行後,模擬器進程將自動停止。
旗幟說明
--only可選的。限制哪些模擬器啟動。提供以逗號分隔的模擬器名稱列表,指定“firestore”、“database”、“functions”、“hosting”或“pubsub”中的一個或多個。
--inspect-functions debug_port可選的。與 Cloud Functions 模擬器一起使用可在指定端口(或默認端口 9229,如果省略參數)啟用函數的斷點調試。請注意,當提供此標誌時,Cloud Functions 模擬器會切換到特殊的序列化執行模式,其中函數在單個進程中按順序 (FIFO) 順序執行;這簡化了函數調試,儘管其行為不同於雲中函數的多進程、並行執行。
--export-on-exit=可選的。與 Authentication、Cloud Firestore、Realtime Database 或 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可選的。與 Authentication、Cloud Firestore、Realtime Database 或 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 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 系統集成

運行容器化的 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 firebase emulators:exec命令。

使用模擬器中心 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 集成

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

客戶端 SDK 可用性

安卓蘋果平台網絡Firebase 界面
安卓
Firebase 界面
iOS
Firebase 界面
網絡
實時數據庫19.4.0 7.2.0 8.0.0 6.4.0未來不適用
雲防火牆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未來
雲防火牆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未來未來未來
雲函數不適用不適用不適用不適用
託管不適用不適用不適用不適用
擴展不適用不適用不適用不適用