Firestore是如何存储数据的，以及如何使用它来执行CRUD操作

步骤3 – 创建：添加任务

Firestore提供了两种创建文档的方法：让Firestore自动生成ID，或者您自己指定ID。

使用addDoc()自动生成ID

// create-task.js
import { collection, addDoc, Timestamp } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function createTask() {
  try {
    const docRef = await addDoc(collection(db, "tasks"), {
      title: "编写CRUD文章",
      completed: false,
      tags: ["writing", "firebase"],
      metadata: {
        priority: "high",
        dueDate: Timestamp.fromDate(new Date("2026-09-15")),
      },
      createdAt: Timestamp.now(),
    });
    console.log("任务创建成功，其ID为：", docRef.id);
  } catch (error) {
    console.error("创建任务时出现错误：", error);
  }
}

createTask();

使用setDoc()自定义文档ID

当您希望自行控制文档ID时，可以使用这种方法，例如将其与另一个系统中的ID进行匹配。

import { doc, setDoc } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function createTaskWithId(taskId) {
  await setDoc(doc(db, "tasks", taskId), {
    title: "Review pull request",
    completed: false,
    tags: ["code-review"],
  });
}

createTaskWithId("task-001");

将文档添加到子集合中

若要在特定任务下添加评论，首先需要引用该任务的父文档：

import { collection, addDoc, Timestamp } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function addComment(taskId, text) {
  await addDoc(collection(db, "tasks", taskId, "comments"), {
    text,
    createdAt: Timestamp.now(),
  });
}

addComment("task-001", "First draft done");

步骤4 – 阅读：查询任务信息

获取单个文档

import { doc, getDoc } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function getTask(taskId) {
  const snapshot = await getDoc(doc(db, "tasks", taskId));
  if (snapshotexists()) {
    console.log(snapshot.id, snapshot.data());
  } else {
    console.log("没有找到该任务。");
  }
}

getTask("task-001");

获取整个集合

import { collection, getDocs } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function getAllTasks() {
  const snapshot = await getDocs(collection(db, "tasks"));
  snapshot.forEach((doc) => {
    console.log(doc.id, doc.data());
  });
}

getAllTasks();

使用查询进行过滤

import { collection, query, where, orderBy, limit, getDocs } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function getUrgentPendingTasks() {
  const q = query(
    collection(db, "tasks"),
    where("completed", "==", false),
    orderBy("metadata.priority"),
    limit(10)
  );

  const snapshot = await getDocs(q);
  snapshot.forEach((doc) => console.log(doc.id, doc.data()));
}

getUrgentPendingTasks();

注意：当在一个字段上使用where()进行过滤，在另一个字段上使用orderBy()进行排序时，通常需要创建一个复合索引。Firestore会在控制台中显示错误信息，并提供创建该索引的详细说明。更多相关内容请参阅“调试”章节。

使用onSnapshot()实现实时更新

您不必一次性获取所有数据，而是可以订阅实时变化。这对于需要在各种设备上即时更新的任务列表来说非常有用：

import { collection, onSnapshot } from "firebase/firestore";
import { db } from "./firebase-config.js";

const unsubscribe = onSnapshot(collection(db, "tasks"), (snapshot) => {
  snapshot.docChanges().forEach((change) => {
    console.log/change.type, change.doc.id, change.doc.data());
  });
});

// 当您不再需要接收更新时，调用unsubscribe()方法（例如，组件被卸载时）

步骤 5 – 更新：修改任务

使用updateDoc()进行部分更新

与setDoc()不同，updateDoc()只会修改您指定的字段，文档中的其他内容保持不变。

import { doc, updateDoc } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function completeTask(taskId) {
  await updateDoc(doc(db, "tasks", taskId), {
    completed: true,
  });
}

completeTask("task-001");

使用点表示法更新嵌套字段

要修改metadata对象中的某个属性，您无需重新编写整个对象：

await updateDoc(doc(db, "tasks", "task-001"), {
  "metadata.priority": "low",
});

安全地更新数组

在并发环境中，直接覆盖数组字段是危险的。应使用arrayUnion()和arrayRemove()方法来操作数组：

import { doc, updateDoc, arrayUnion, arrayRemove } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function addTag(taskId, tag) {
  await updateDoc(doc(db, "tasks", taskId), {
    tags: arrayUnion(tag),
  });
}

async function removeTag(taskId, tag) {
  await updateDoc(doc(db, "tasks", taskId), {
    tags: arrayRemove(tag),
  });
}

arrayUnion()会去除重复的值，而arrayRemove()则会删除所有匹配的条目。这两种操作都在服务器端原子性地执行。

步骤 6 – 删除：移除任务

删除文档

import { doc, deleteDoc } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function deleteTask(taskId) {
  await deleteDoc(doc(db, "tasks", taskId));
}

deleteTask("task-001");

子集合的陷阱

前面提到过一个需要注意的问题：删除tasks/task-001并不会自动删除其对应的comments子集合。这些评论文档仍然存在于数据库中，只是通过用户界面无法访问它们，除非您知道它们的路径。

要正确地进行清理操作，首先需要删除子集合中的文档，然后再删除父集合中的文档：

import { collection, getDocs, doc, deleteDoc, writeBatch } from "firebase/firestore";
import { db } from "./firebase-config.js";

async function deleteTaskWithComments(taskId) {
  const commentsRef = collection(db, "tasks", taskId, "comments");
  const commentsSnapshot = await getDocs(commentsRef);

  const batch = writeBatch(db);
  commentsSnapshot.forEach((commentDoc) => {
    batch.delete(commentDoc.ref);
  });
  batch.delete(doc(db, "tasks", taskId));

  await batch.commit();
}

deleteTaskWithComments("task-001");

writeBatch() 将多个删除操作合并为一次原子性操作。这些操作要么全部成功，要么全部失败。

删除单个字段

如果你只想删除某个字段而不想删除整个文档，可以使用 deleteField() 方法：

import { doc, updateDoc, deleteField } from "firebase/firestore";
import { db } from "./firebase-config.js";

await updateDoc(doc(db, "tasks", "task-001"), {
  metadata: deleteField(),
});

调试常见问题

FirebaseError: 缺少或权限不足

你的安全规则阻止了该请求的执行。如果你仍处于测试模式，请检查30天的有效期是否已经到期（过了这个期限，规则会自动恢复为拒绝所有请求）。对于正式发布的应用程序，请在Firestore设置中查看规则配置，然后检查这些规则是否与你实际进行读写操作的路径相匹配，包括子集合；子集合也需要单独设置规则。

函数 addDoc() 被调用时传入了无效数据。不支持的值：undefined

与null不同，undefined值是被Firestore明确拒绝的。这种情况通常发生在表单字段为空时，你直接将其传递给写入操作。在进行写入操作之前，请先过滤掉所有值为undefined的字段，或者将它们的值设置为null。

该查询需要索引才能执行

当你在不同的字段上同时使用where()和orderBy()时，就会出现这种错误。Firestore无法利用自动创建的索引来执行这样的查询。错误信息中会提供一个链接，通过这个链接可以在控制台中预先生成所需的复合索引。点击该链接，等待一两分钟让索引生成完成，然后再重新执行查询即可。

读取操作次数过多导致配额警告

无论是在循环中多次调用getDoc()，还是直接获取整个集合的数据，每次操作都会被计为一次读取。为了避免不必要的数据传输，请不要为了在客户端进行过滤而先获取整个集合，而是应该使用where()在查询阶段就完成过滤操作；对于那些可能会无限增长的数据集，还需要使用limit()来限制查询结果的数量。

删除后剩余的子集合

如果您发现认为自己已经删除的文档仍在占用存储空间，或者仍然出现在导出结果中，请检查被删除文档路径下是否存在子集合。正如步骤6中所说明的，deleteDoc()方法永远不会触发级联删除操作，因此清理这些剩余的子集合始终是您的责任。

总结

现在，您已经对Firestore的数据结构有了清晰的认识，并且也通过使用Web SDK v9+亲自体验了所有的CRUD操作。以下是这些内容的简要回顾：

操作类型	关键函数
创建	addDoc(), setDoc()
读取	getDoc(), getDocs(), query(), onSnapshot()
更新	updateDoc(), arrayUnion(), arrayRemove()
删除	deleteDoc(), deleteField(), writeBatch()

当您熟练掌握了这些基础知识之后，接下来可以尝试以下几个方向进行进一步学习：

• 事务处理，用于那些必须同时成功或失败的操作（例如在两个用户之间传递任务）。

• 批量写入操作，正如步骤6中所介绍的，当您需要原子性地修改多份文档时，这种操作非常有用。

• 复合索引，可以帮助您实现更复杂的过滤和排序功能。

• 分页处理，通过使用startAfter()方法，可以分批加载大量数据，而无需一次性全部加载。

如果您还没有这样做的话，建议在针对数据编写查询语句之前，先重新思考如何对数据进行建模。在建模阶段做出的决策（比如是否需要嵌套数据或使用子集合），会直接影响到后续使用哪些CRUD操作会更加自然、高效。