在本機使用 Firestore 模擬器

Google Cloud CLI 提供 Firestore 的本機記憶體內模擬器，可用來測試應用程式。您可以搭配所有 Firestore 用戶端程式庫使用模擬器。請只將模擬器用於本機測試。

請勿將模擬器用於正式版部署作業。由於模擬器只會在記憶體中儲存資料，因此不會在執行期間保留資料。

安裝模擬器

如要安裝 Firestore 模擬器，請安裝及更新 gcloud CLI：

  1. 安裝 gcloud CLI。

  2. 更新 gcloud CLI 安裝項目，取得最新功能：

    gcloud components update

執行模擬器

  1. 執行以下指令來啟用模擬器：

    gcloud emulators firestore start

    模擬器會顯示正在執行的主機和通訊埠編號。

    根據預設，模擬器會嘗試使用 127.0.0.1:8080。如要將模擬器繫結到特定主機和通訊埠，請使用選用的 --host-port 標記，並取代 HOST 和 PORT：

    gcloud emulators firestore start --host-port=HOST:PORT

  2. 輸入 Control + C 即可停止模擬器。您也可以透過 POST 傳送至 /shutdown 來停止模擬器。例如：

    curl -d '' HOST:PORT/shutdown

連線至模擬器

連線至模擬器的方式取決於用戶端程式庫、伺服器用戶端程式庫或行動/網頁 SDK 的類型。

伺服器用戶端程式庫

如要連線 Firestore 伺服器用戶端程式庫 (C#、Go、Java、Node.js、PHP、Python 和 Ruby)，請設定 FIRESTORE_EMULATOR_HOST 環境變數。設定這項環境變數後，伺服器用戶端程式庫會自動連線至模擬器。

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

Android、Apple 平台和 Web SDK

下列範例說明如何將 Android、Apple 平台和 Web SDK 連線至 Firestore 模擬器：

Android
// 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 = settings
ViewController.swift

網頁版 9

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

網頁版 8

// 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 模擬器會清除資料庫內容。由於 Firestore SDK 的離線快取不會自動清除，您可能需要在模擬器設定中停用本機持續性，以免模擬的資料庫與本機快取之間出現差異；在 Web SDK 中，持續性預設為停用。

清除模擬器資料

Firestore 模擬器包含 REST 端點，可刪除模擬器中的所有資料。您可以使用這個端點清除測試之間的資料，不必關閉模擬器。

如要刪除模擬器中的所有資料，請對下列端點執行 HTTP DELETE 作業，並將 HOST 和 PORT 替換為您選取的主機和連接埠，並將 PROJECT_ID 替換為您自己的專案 ID：

http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents

如果模擬器未使用 127.0.0.1:8080，請調整主機和通訊埠。 您的程式碼應等待 REST 確認刪除作業完成或失敗。

您可以使用 curl 從殼層執行這項作業：

$ curl -v -X DELETE "http://HOST:PORT/emulator/v1/projects/PROJECT_ID/databases/(default)/documents"

Firestore 模擬器與正式版之間的差異

Firestore 模擬器會盡量模擬正式版服務的行為，但仍有幾項明顯限制。

交易

模擬器不會嘗試模擬實際環境中的交易行為。這個範例採用簡單的鎖定方法，並未嘗試模擬實際工作環境提供的各種並行模式。

測試涉及對單一文件進行多項並行寫入作業的功能時，模擬器可能需要較長時間才能完成寫入要求。模擬器最多可能需要 30 秒才能釋放鎖定。如需調整測試逾時間隔，請進行調整。

模擬器也不會嘗試模擬所有生產限制，例如涉及交易的逾時和大小限制。如果您測試的功能會受到這些正式版限制影響，建議使用正式版環境，而非模擬器。

索引

模擬器不會追蹤複合索引，而是執行任何有效的查詢。請務必針對實際的 Firestore 執行個體測試應用程式，判斷您需要哪些索引。

限制

模擬器不會強制執行正式環境中的所有限制。舉例來說，模擬器可能會允許交易，但實際工作環境服務會因交易過大而拒絕。請務必熟讀文件中的限制，並在設計應用程式時主動避開這些限制。