在本地模拟 Firestore

Google Cloud CLI 提供了适用于 Firestore 的本地内存模拟器，可用于测试应用。您可以将模拟器与所有 Firestore 客户端库搭配使用。您只能将模拟器用于本地测试。

请勿将模拟器用于生产部署。由于模拟器仅将数据存储在内存中，因此数据在各次运行之间不会保留。

安装模拟器

如需安装 Firestore 模拟器，请安装和更新 gcloud CLI：

安装 gcloud CLI。
更新您的 gcloud CLI 安装以获取最新功能：
```
gcloud components update
```

运行模拟器

运行以下命令启动模拟器：
```
gcloud emulators firestore start
```
该模拟器将输出其运行所在的主机和端口号。

默认情况下，模拟器会尝试使用 localhost:8080。如需将模拟器绑定到特定主机和端口，请使用可选的 --host-port 标志，并替换 HOST 和 PORT：
```
gcloud emulators firestore start --host-port=HOST:PORT
```
输入 Control + C 以停止模拟器。

连接到模拟器

您连接到模拟器的方式取决于客户端库、服务器客户端库或移动/Web SDK 的类型。

服务器客户端库

如需连接 Firestore 服务器客户端库（C#、Go、Java、Node.js、PHP、Python 和 Ruby），请设置 FIRESTORE_EMULATOR_HOST 环境变量。设置此环境变量后，服务器客户端库会自动连接到模拟器。

export FIRESTORE_EMULATOR_HOST="HOST:PORT"

Android、Apple 平台和 Web SDK

以下示例演示了如何将 Android SDK、Apple 平台 SDK 和 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 = "localhost:8080"
settings.isPersistenceEnabled = false
settings.isSSLEnabled = false
Firestore.firestore().settings = settingsViewController.swift

Web 版本 9

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

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

Web 版本 8

// Firebase previously initialized using firebase.initializeApp().
var db = firebase.firestore();
if (location.hostname === "localhost") {
  db.useEmulator("localhost", 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

如果模拟器未使用 localhost:8080，请调整主机和端口。您的代码应等待关于删除完成或失败的 REST 确认信息。

您可以使用 curl 在 shell 中执行此操作：

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

Firestore 模拟器与生产环境的区别

Firestore 模拟器会尝试真实地重现生产服务的行为，但存在一些值得注意的限制。

事务

模拟器无法实现在生产环境中出现的所有事务行为。当您要测试涉及对一个文档执行多次并发写入的功能时，模拟器完成写入请求的速度可能会很慢。在某些情况下，对数据的锁定可能需要长达 30 秒才会解除。如有需要，请考虑相应地调整测试超时时长。

索引

模拟器不会跟踪复合索引，而是执行任何有效的查询。请务必对照真实的 Firestore 实例测试您的应用，以确定您需要哪些索引。

限制

模拟器不会强制执行生产环境中强制执行的所有限制。例如，模拟器可能会允许因为过大而会被生产服务拒绝的事务。请确保您熟悉文档中说明的限制，并且将您的应用设计为主动避免超出这些限制。