Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

將應用程式連線至 Cloud Firestore 模擬器

將應用程式連結至 Cloud Firestore 模擬器之前，請務必瞭解 Firebase Local Emulator Suite 的整體工作流程，並安裝及設定 Local Emulator Suite，以及查看其 CLI 指令。

選擇 Firebase 專案

Firebase Local Emulator Suite 會模擬單一 Firebase 專案的產品。

如要選取要使用的專案，請在啟動模擬器前，在 CLI 的目前使用的目錄中執行 firebase use。或者，您也可以將 --project 旗標傳遞至每個模擬器指令。

Local Emulator Suite 支援模擬「實際」Firebase 專案和「示範」專案。

專案類型功能搭配模擬器使用

實數

專案類型	功能	搭配模擬器使用
實數	實際的 Firebase 專案是指您建立及設定的專案 (通常是透過 Firebase 控制台)。實際專案含有實際資源，例如資料庫執行個體、Storage bucket、函式，或您為該 Firebase 專案設定的其他資源。	使用實際的 Firebase 專案時，您可以為任何或所有支援的產品執行模擬器。對於未模擬的產品，應用程式和程式碼會與實際資源 (資料庫執行個體、儲存空間 bucket、函式等) 互動。
示範	Firebase 示範專案沒有「實際」Firebase 設定，也沒有任何實際資源。這類專案通常可透過程式碼實驗室或其他教學課程存取。示範專案的專案 ID 具有 `demo-` 前置字元。	使用 Firebase 示範專案時，應用程式和程式碼「只會」與模擬器互動。如果應用程式嘗試與未執行模擬器的資源互動，該程式碼就會失敗。

實際的 Firebase 專案是指您建立及設定的專案 (通常是透過 Firebase 控制台)。

實際專案含有實際資源，例如資料庫執行個體、Storage bucket、函式，或您為該 Firebase 專案設定的其他資源。

使用實際的 Firebase 專案時，您可以為任何或所有支援的產品執行模擬器。

對於未模擬的產品，應用程式和程式碼會與實際資源 (資料庫執行個體、儲存空間 bucket、函式等) 互動。

示範

Firebase 示範專案沒有「實際」Firebase 設定，也沒有任何實際資源。這類專案通常可透過程式碼實驗室或其他教學課程存取。

示範專案的專案 ID 具有 demo- 前置字元。

使用 Firebase 示範專案時，應用程式和程式碼「只會」與模擬器互動。如果應用程式嘗試與未執行模擬器的資源互動，該程式碼就會失敗。

建議您盡可能使用試用專案。包括以下優點：

設定更簡單，因為您不必建立 Firebase 專案，就能執行模擬器
安全性更高，因為如果程式碼不小心叫用非模擬 (正式環境) 資源，就不會發生資料變更、用量和計費
離線支援更完善，因為不需要連上網際網路，就能下載 SDK 設定。

檢測應用程式，以便與模擬器通訊

Cloud Firestore 模擬器啟動時，會為 firebase.json 檔案中的每個 firestore 設定建立預設資料庫和具名資料庫。

如果對模擬器發出任何 SDK 或 REST API 呼叫，且參照特定資料庫，系統也會隱含建立具名資料庫。這類隱含建立的資料庫會依據開放規則運作。

如要在 Emulator Suite UI 中以互動方式使用預設和命名資料庫，請在瀏覽器的網址列中更新網址，選取預設或命名資料庫。

舉例來說，如要瀏覽預設執行個體中的資料，請將網址更新為 localhost:4000/firestore/default/data
如要在名為 ecommerce 的執行個體中瀏覽，請更新至 localhost:4000/firestore/ecommerce/data。

啟動特定版本的模擬器

模擬器會以 firebase.json 檔案 firestore.edition 區段中指定的版本啟動。您也可以在 firebase.json 的 emulators.firestore.edition 區段下指定版本。版本有效值為 standard 和 enterprise。如果您在兩項設定中都指定 edition，則 emulators.firestore.edition 優先。

    {
      ...
      "firestore": {
        "rules": "firestore.rules",
        "indexes": "firestore.indexes.json",
        "edition": "enterprise"
      },
      "emulators": {
        "firestore": {
          "port": 8080,
          "edition": "enterprise" // Takes precedence over `firestore.edition`
        }
      },
      ...
    }

Android、Apple 平台和網頁 SDK

請按照下列方式設定應用程式內設定或測試類別，以便與 Cloud Firestore 互動。請注意，在下列範例中，應用程式程式碼會連線至預設專案資料庫。如需預設資料庫以外的其他 Cloud Firestore 資料庫範例，請參閱多資料庫指南。

Kotlin

// 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

Swift

let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.cacheSettings = MemoryCacheSettings()
settings.isSSLEnabled = false
Firestore.firestore().settings = settingsViewController.swift

Unity

預設主機為 127.0.0.1。如果您使用的是 Android 模擬器，則必須使用 10.0.2.2。

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
// Connects to the Firestore Emulator running on port 8080
db.Settings.Host = "127.0.0.1:8080";
db.Settings.SslEnabled = false;

Web

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

// 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 模擬器同時執行時，會自動搭配運作。

Admin SDK 秒

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

export FIRESTORE_EMULATOR_HOST="127.0.0.1:8080"

如果程式碼在 Cloud Functions 模擬器中執行，呼叫 initializeApp 時，系統會自動設定專案 ID 和其他設定。

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

Node.js Admin SDK

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

環境變數

export GCLOUD_PROJECT="your-project-id"

Cloud Firestore REST API

Cloud Firestore 模擬器提供 REST 端點，可與資料庫互動。所有 REST API 呼叫都應傳送至 http://localhost:8080/v1 端點。

REST 呼叫的完整路徑格式如下：

http://localhost:8080/v1/projects/{project_id}/databases/{database_id}/documents/{document_path}

舉例來說，如要列出專案 my-project-id 的 users 集合中的所有文件，可以使用 curl：

curl -X GET "http://localhost:8080/v1/projects/my-project-id/databases/(default)/documents/users"

在測試之間清除資料庫

正式版 Firestore 未提供清除資料庫的平台 SDK 方法，但 Firestore 模擬器提供專門用於此目的的 REST 端點，可在測試開始前，從測試架構設定/tearDown 步驟、測試類別或殼層 (例如使用 curl) 呼叫。您可以採用這種方法，而不只是關閉模擬器程序。

請在適當的方法中執行 HTTP DELETE 作業，並將 Firebase 專案 ID (例如 firestore-emulator-example) 提供給下列端點：

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

程式碼應等待 REST 確認清除作業完成或失敗。

您可以透過殼層執行這項作業：

// 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 指令。詳情請參閱模擬器指令參考資料。

以圖表呈現安全性規則活動

在原型設計和測試循環中，您可以使用 Local Emulator Suite 提供的視覺化工具和報表。

使用要求監控工具

Cloud Firestore 模擬器可讓您在 Emulator Suite UI 中以視覺化方式呈現用戶端要求，包括 Firebase Security Rules 的評估追蹤。

開啟「Firestore」>「Requests」分頁，查看每項要求的詳細評估序列。

Firestore 模擬器要求監控工具，顯示安全性規則評估結果

以圖表呈現規則評估報表

在原型中新增安全性規則時，可以使用 Local Emulator Suite 偵錯工具進行偵錯。

執行一系列測試後，您可以查看測試涵蓋率報表，瞭解每項安全性規則的評估方式。

如要取得報表，請在模擬器執行時查詢公開的端點。如要使用適合瀏覽器的版本，請使用下列網址：

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

這會將規則拆分為運算式和子運算式，您可以將滑鼠游標懸停在這些運算式上，查看更多資訊，包括評估次數和傳回的值。如要取得這項資料的原始 JSON 版本，請在查詢中加入下列網址：

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 執行個體測試應用程式，判斷需要哪些索引。

限制

模擬器不會強制執行正式環境中的所有限制。舉例來說，模擬器可能會允許正式版服務因過大而拒絕的交易。請務必熟悉記錄的限制，並設計應用程式，主動避免這些限制。

後續步驟

如需精選影片和詳細的 How-to 範例，請觀看 Firebase 模擬器訓練播放清單。
研究涉及安全性規則測試和 Firebase Test SDK 的進階用途：測試安全性規則 (Firestore)。
觸發函式通常會與 Cloud Firestore 整合，如要進一步瞭解 Cloud Functions for Firebase 模擬器，請參閱「在本機執行函式」。