將您的應用連接到 Cloud Firestore 模擬器

在將您的應用連接到 Cloud Firestore 模擬器之前，請確保您了解 Firebase Local Emulator Suite 的整體工作流程，並安裝和配置Local Emulator Suite 並查看其CLI 命令。

選擇一個 Firebase 項目

Firebase 本地模擬器套件模擬單個 Firebase 項目的產品。

要選擇要使用的項目，在啟動模擬器之前，請在 CLI 中在您的工作目錄中運行firebase use 。或者，您可以將--project標誌傳遞給每個模擬器命令。

注意：對所有模擬器調用使用一個項目 ID 通常是一種很好的做法，因此 Emulator Suite UI、不同的產品模擬器以及特定模擬器的所有正在運行的實例在所有情況下都可以正確通信。事實上，默認情況下，本地模擬器套件會在檢測到多個正在使用的項目 ID 時發出警告，儘管您可以覆蓋此行為。有關設置和管理項目 ID 的指南，請參閱安裝和配置指南。

Local Emulator Suite 支持模擬真實的Firebase 項目和演示項目。

項目類型	特徵	與模擬器一起使用
真實的	真正的 Firebase 項目是您創建和配置的項目（很可能通過 Firebase 控制台）。 真實項目具有實時資源，例如數據庫實例、存儲桶、函數或您為該 Firebase 項目設置的任何其他資源。	在處理真正的 Firebase 項目時，您可以為任何或所有受支持的產品運行模擬器。 對於您未模擬的任何產品，您的應用程序和代碼將與實時資源（數據庫實例、存儲桶、函數等）進行交互。
演示	演示 Firebase 項目沒有真正的Firebase 配置，也沒有實時資源。這些項目通常通過代碼實驗室或其他教程訪問。 演示項目的項目 ID 具有demo-前綴。	使用演示 Firebase 項目時，您的應用和代碼僅與模擬器交互。如果您的應用程序嘗試與未運行模擬器的資源進行交互，則該代碼將失敗。

我們建議您盡可能使用演示項目。好處包括：

• 設置更簡單，因為您無需創建 Firebase 項目即可運行模擬器
• 更強的安全性，因為如果您的代碼意外調用非模擬（生產）資源，則不會發生數據更改、使用和計費
• 更好的離線支持，因為無需訪問互聯網即可下載您的 SDK 配置。

注意：如果要模擬跨服務交互，例如依賴身份驗證的數據庫觸發的雲函數或規則，則必須確保代碼中的項目 ID（在initializeApp()等中）與所使用的項目 ID 匹配Firebase CLI。

檢測您的應用程序以與模擬器對話

Android、Apple 平台和 Web SDK

設置應用內配置或測試類以與 Cloud Firestore 交互，如下所示。

注意： Cloud Firestore 模擬器在關閉時會清除數據庫內容。由於 Firestore SDK 的離線緩存不會自動清除，您可能需要在模擬器配置中禁用本地持久性以避免模擬數據庫和本地緩存之間的差異；在 Web SDK 中，默認情況下禁用持久性。

安卓

// 10.0.2.2 is the special IP address to connect to the 'localhost' of
// the host computer from an Android emulator.
FirebaseFirestore firestore = FirebaseFirestore.getInstance();
firestore.useEmulator("10.0.2.2", 8080);

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(false)
        .build();
firestore.setFirestoreSettings(settings);
EmulatorSuite.java

迅速

let settings = Firestore.firestore().settings
settings.host = "localhost:8080"
settings.isPersistenceEnabled = false 
settings.isSSLEnabled = false
Firestore.firestore().settings = settings
ViewController.swift

Web version 9

詳細了解可搖樹的 Web v9 模塊化 SDK 並從版本 8升級。

import { getFirestore, connectFirestoreEmulator } from "firebase/firestore";

// firebaseApps previously initialized using initializeApp()
const db = getFirestore();
connectFirestoreEmulator(db, 'localhost', 8080);
fs_emulator_connect.js

Web version 8

詳細了解可搖樹的 Web v9 模塊化 SDK 並從版本 8升級。

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("localhost", 8080);
}
emulator-suite.js

無需額外設置即可使用模擬器測試由 Firestore 事件觸發的Cloud Functions。當 Firestore 和 Cloud Functions 模擬器都在運行時，它們會自動協同工作。

管理 SDK

設置FIRESTORE_EMULATOR_HOST環境變量後，Firebase Admin SDK 會自動連接到 Cloud Firestore 模擬器：

export FIRESTORE_EMULATOR_HOST="localhost:8080"

如果您的代碼在 Cloud Functions 模擬器中運行，您的項目 ID 和其他配置將在調用initalizeApp時自動設置。

如果您希望您的 Admin SDK 代碼連接到在另一個環境中運行的共享模擬器，則需要指定您使用 Firebase CLI 設置的相同項目 ID 。您可以將項目 ID 直接傳遞給initializeApp或設置GCLOUD_PROJECT環境變量。

Node.js 管理 SDK

admin.initializeApp({ projectId: "your-project-id" });

環境變量

export GCLOUD_PROJECT="your-project-id"

在測試之間清除數據庫

生產 Firestore 沒有提供用於刷新數據庫的平台 SDK 方法，但 Firestore 模擬器為您提供了專門用於此目的的 REST 端點，可以從測試框架設置/拆卸步驟、測試類或外殼程序調用該端點（例如, curl ) 在測試開始之前。您可以使用此方法作為簡單關閉模擬器進程的替代方法。

在適當的方法中，執行 HTTP DELETE 操作，將您的 Firebase projectID（例如firestore-emulator-example ）提供給以下端點：

"http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

自然，您的代碼應該等待 REST 確認刷新完成或失敗。

您可以從 shell 執行此操作：

// Shell alternative…
$ curl -v -X DELETE "http://localhost:8080/emulator/v1/projects/firestore-emulator-example/databases/(default)/documents"

實施了這樣的步驟後，您可以對測試進行排序並觸發您的函數，確信舊數據將在運行之間被清除，並且您正在使用新的基線測試配置。

導入和導出數據

Firebase 模擬器的數據庫和 Cloud Storage 允許您從正在運行的模擬器實例中導出數據。定義要在單元測試或持續集成工作流中使用的基線數據集，然後將其導出以在團隊之間共享。

firebase emulators:export ./dir

在測試中，在模擬器啟動時，導入基線數據。

firebase emulators:start --import=./dir

您可以指示模擬器在關機時導出數據，可以指定導出路徑，也可以簡單地使用傳遞給--import標誌的路徑。

firebase emulators:start --import=./dir --export-on-exit

這些數據導入和導出選項也適用於firebase emulators:exec命令。有關更多信息，請參閱模擬器命令參考。

可視化安全規則活動

在完成原型和測試循環時，您可以使用 Local Emulator Suite 提供的可視化工具和報告。

使用請求監視器

Cloud Firestore 模擬器可讓您在 Emulator Suite UI 中可視化客戶端請求，包括 Firebase 安全規則的評估跟踪。

打開Firestore > Requests選項卡以查看每個請求的詳細評估順序。

可視化規則評估報告

當您將安全規則添加到您的原型時，您可以使用本地仿真器套件調試工具對其進行調試。

運行一套測試後，您可以訪問測試覆蓋率報告，顯示您的每個安全規則是如何評估的。

要獲取報告，請在模擬器運行時查詢其暴露的端點。對於瀏覽器友好的版本，請使用以下 URL：

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage.html

這會將您的規則分解為表達式和子表達式，您可以將鼠標懸停以獲取更多信息，包括評估的數量和返回的值。對於此數據的原始 JSON 版本，請在查詢中包含以下 URL：

http://localhost:8080/emulator/v1/projects/<database_name>:ruleCoverage

在這裡，報告的 HTML 版本突出顯示了引發未定義和空值錯誤的評估：

Cloud Firestore 模擬器與生產環境有何不同

Cloud Firestore 模擬器嘗試忠實地複制生產服務的行為，但存在一些明顯的限制。

交易

模擬器當前並未實現生產中看到的所有事務行為。當您測試涉及多個並發寫入一個文檔的功能時，模擬器完成寫入請求可能會很慢。在某些情況下，鎖定可能需要長達 30 秒才能釋放。如果需要，請考慮相應地調整測試超時。

索引

模擬器不跟踪複合索引，而是執行任何有效的查詢。確保針對真實的 Cloud Firestore 實例測試您的應用，以確定您需要哪些索引。

限制

模擬器不會強制執行生產中強制執行的所有限制。例如，模擬器可能允許因生產服務太大而被拒絕的事務。確保您熟悉記錄在案的限制，並確保您在設計應用時主動避免這些限制。

接下來是什麼？

• 如需一組精選視頻和詳細的操作示例，請關注Firebase 模擬器培訓播放列表。
• 調查涉及安全規則測試和 Firebase 測試 SDK 的高級用例：測試安全規則 (Firestore) 。
• 由於觸發函數是與 Cloud Firestore 的典型集成，因此請在本地運行函數中了解有關 Cloud Functions for Firebase 模擬器的更多信息。