Firebase Demo Day is here! Watch demos of how to build and grow AI-powered, full stack apps using the best of Google.

本頁面由 Cloud Translation API 翻譯而成。

Switch to English

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

在將您的應用程式連接到 Cloud Firestore 模擬器之前，請確保您了解 Firebase 本機模擬器套件的整體工作流程，並安裝和設定本機模擬器套件並查看其CLI 命令。

選擇 Firebase 項目

Firebase 本機模擬器套件模擬單一 Firebase 專案的產品。

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

本機模擬器套件支援模擬真實的Firebase 專案和演示專案。

項目類型特徵與模擬器一起使用

真實的

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

真正的 Firebase 專案是您建立和配置的專案（很可能透過 Firebase 控制台）。

真實專案具有即時資源，例如資料庫執行個體、儲存桶、函數或您為該 Firebase 專案設定的任何其他資源。

在處理真實的 Firebase 專案時，您可以為任何或所有受支援的產品運行模擬器。

對於您未模擬的任何產品，您的應用程式和程式碼將與即時資源（資料庫執行個體、儲存桶、函數等）進行互動。

示範

示範 Firebase 專案沒有真正的Firebase 配置，也沒有即時資源。這些項目通常透過代碼實驗室或其他教程存取。

示範項目的項目 ID 具有demo-前綴。

使用示範 Firebase 專案時，您的應用程式和程式碼僅與模擬器互動。如果您的應用程式嘗試與未運行模擬器的資源進行交互，則該程式碼將會失敗。

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

設定更簡單，因為您無需建立 Firebase 專案即可運行模擬器
更強的安全性，因為如果您的程式碼意外調用非模擬（生產）資源，則不會發生資料變更、使用和計費
更好的離線支持，因為無需訪問互聯網即可下載 SDK 配置。

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

啟動時，Cloud Firestore 模擬器會為firebase.json檔案中的每個firestore配置建立一個預設資料庫和一個命名資料庫。使用firebase.json檔案將 Cloud Firestore 安全性規則明確指派給指定資料庫。

命名資料庫也會隱式創建，以回應對引用特定資料庫的模擬器的任何 SDK 或 REST API 呼叫。這種隱式創建的資料庫按照開放規則運作。

目前，Emulator Suite UI 支援與預設資料庫的互動工作。

Android、Apple 平台和 Web SDK

設定應用程式內配置或測試類別以與 Cloud Firestore 交互，如下所示。請注意，在以下範例中，應用程式程式碼連接到預設專案資料庫。有關涉及預設資料庫以外的其他 Cloud Firestore 資料庫的範例，請參閱多個資料庫指南。

Kotlin+KTX

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

firestore.firestoreSettings = firestoreSettings {
    isPersistenceEnabled = false
}EmulatorSuite.kt

Java

// 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 = "127.0.0.1:8080"
settings.isPersistenceEnabled = false
settings.isSSLEnabled = false
Firestore.firestore().settings = settingsViewController.swift

Web modular API

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

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

Web namespaced API

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

使用模擬器測試由 Firestore 事件觸發的Cloud Functions 無需進行任何額外設定。當 Firestore 和 Cloud Functions 模擬器同時運作時，它們會自動協同運作。

管理 SDK

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

如果您的程式碼在 Cloud Functions 模擬器內執行，您的專案 ID 和其他配置將在呼叫initializeApp時自動設定。

如果您希望 Admin SDK 程式碼連接到在其他環境中執行的共用模擬器，則需要指定使用 Firebase CLI 設定的相同專案 ID 。您可以直接將專案ID傳遞給initializeApp或設定GCLOUD_PROJECT環境變數。

Node.js 管理 SDK

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

環境變數

export GCLOUD_PROJECT="your-project-id"

在測試之間清除資料庫

Production Firestore 不提供用於刷新資料庫的平台 SDK 方法，但 Firestore 模擬器為您提供了專門用於此目的的 REST 端點，可以從測試框架設定/拆卸步驟、測試類別或 shell（例如，使用curl ）在測試開始之前。您可以使用此方法作為簡單關閉模擬器進程的替代方法。

在適當的方法中，執行 HTTP DELETE 操作，為下列端點提供您的 Firebase 專案 ID（例如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"

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

導入導出數據

資料庫和 Cloud Storage for Firebase 模擬器可讓您從正在執行的模擬器實例匯出資料。定義要在單元測試或持續整合工作流程中使用的基準資料集，然後將其匯出以在團隊之間共用。

firebase emulators:export ./dir

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

firebase emulators:start --import=./dir

您可以指示模擬器在關閉時匯出數據，可以指定匯出路徑，也可以只使用傳遞給--import標誌的路徑。

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

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

可視化安全規則活動

當您完成原型和測試循環時，您可以使用本機模擬器套件提供的視覺化工具和報告。

使用請求監視器

Cloud Firestore 模擬器可讓您在模擬器套件 UI 中視覺化用戶端請求，包括 Firebase 安全規則的評估追蹤。

開啟Firestore > 請求標籤以查看每個請求的詳細評估順序。

Firestore 模擬器要求監視器顯示安全規則評估

視覺化規則評估報告

當您將安全規則新增至原型時，您可以使用本機模擬器套件偵錯工具對其進行偵錯。

執行一套測試後，您可以存取測試覆蓋率報告，其中顯示每個安全規則的評估。

若要取得報告，請在模擬器執行時查詢模擬器上公開的端點。對於瀏覽器友善的版本，請使用以下 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 模擬器嘗試忠實複製生產服務的行為，但存在一些明顯的限制。

Cloud Firestore 的多資料庫支持

目前，Emulator Suite UI 支援預設資料庫的互動式建立、編輯、刪除、請求監控和安全性視覺化，但不支援其他命名資料庫。

但是，模擬器本身會根據firebase.json檔案中的配置建立一個命名資料庫，並隱含地回應 SDK 或 REST API 呼叫。

交易

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

索引

模擬器不追蹤複合索引，而是執行任何有效的查詢。請務必針對真實的 Cloud Firestore 執行個體測試您的應用，以確定您需要哪些索引。

限制

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

接下來是什麼？

如需一組精選影片和詳細操作範例，請關注Firebase 模擬器訓練播放清單。
研究涉及安全規則測試和 Firebase 測試 SDK 的高級用例：測試安全規則 (Firestore) 。
由於觸發函數是與 Cloud Firestore 的典型集成，因此請在本機上運行函數以了解有關 Cloud Functions for Firebase 模擬器的更多資訊。