在本地使用 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

连接到模拟器

如何连接到模拟器取决于客户端库、服务器客户端库或移动/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、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

Web 版本 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

Web 版本 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 端点，用于删除模拟器中当前的所有数据。您可以使用此端点在测试之间清除数据，而无需关闭模拟器。

如需删除模拟器中的所有数据，请对DELETE 并将 HOST 和 PORT 替换为 主机和端口，并将 PROJECT_ID 替换为您的 自己的项目 ID：

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

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

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

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

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

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

交易

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

索引

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

限制

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