在一个管理后台中批量导入几百条用户数据时，如果每条都单独调用一次Firestore的set()，页面要等待几百次网络往返才能完成。如果中途某条写入失败，已经写入的数据还会留下半成品。Firebase Firestore提供的批量写入（batch）就是为这类场景设计的，它把多次写入操作打包成一个原子提交，调用一次commit()即可提交全部变更。
批量写入解决了什么问题
在没有批量写入能力时，开发者通常用循环逐条执行set()或update()。这种做法有两个明显缺点：一是网络往返次数等于文档数量，当数据量从几十条增加到几百条时，总耗时线性上涨；二是缺乏原子性，如果写到第150条时网络中断，前149条已经成功写入，剩下的一半数据缺失，后续排查和补偿逻辑会很麻烦。
Firestore的writeBatch接口把多次写入合并为一个批量对象，最终只通过一次commit()提交给服务端。服务端要么全部执行成功，要么全部不生效。对于批量导入、批量清理过期数据、批量更新状态这一类不需要读取旧值的场景，batch操作能显著减少延迟，同时保证数据一致性。需要注意的是，Firebase还有另一套数据库叫Realtime Database，它原生并不提供Firestore意义上的batch，但可以通过多路径update()在一次连接中修改多个节点，实现类似的一次提交效果。
如何用WriteBatch完成一次批量提交
在Firestore JavaScript SDK的v9及以上版本中，批量写入通常从writeBatch(db)开始。先创建一个WriteBatch实例，然后向其中添加set、update或delete操作，最后调用commit()。下面的代码演示了写入一个新文档、更新另一个文档字段、删除第三个文档的完整过程。
import { getFirestore, writeBatch, doc, collection } from "firebase/firestore";
async function runBatch() {
const db = getFirestore();
const batch = writeBatch(db);
const citiesRef = collection(db, "cities");
const nycRef = doc(citiesRef, "NYC");
batch.set(nycRef, { name: "New York", population: 8804190 });
const laRef = doc(citiesRef, "LA");
batch.update(laRef, { population: 3898747 });
const sfRef = doc(citiesRef, "SF");
batch.delete(sfRef);
await batch.commit();
console.log("批量提交完成");
}
代码中batch.set()的第一个参数是文档引用，第二个参数是完整的数据对象。如果文档已经存在，set()默认会覆盖全部字段；如果只想更新部分字段，使用batch.update()并传入需要修改的键值对即可。batch.delete()只需要文档引用，不需要第二个参数。执行commit()后，Firestore会原子地应用这批操作，客户端在Promise resolve之后就可以认为数据已经写入成功。
对于数据量较大的场景，不能无脑把所有数据都塞进一个batch，因为Firestore对单次batch有明确的限制。最稳妥的做法是把数据分块，每400条左右提交一次。下面的代码展示了分块提交的常见写法，它每次创建一个新的batch，提交后继续处理下一段数据。
async function writeLargeDataset(items) {
const db = getFirestore();
const chunkSize = 400;
for (let i = 0; i < items.length; i += chunkSize) {
const chunk = items.slice(i, i + chunkSize);
const batch = writeBatch(db);
chunk.forEach(item => {
const ref = doc(db, "items", item.id);
batch.set(ref, item);
});
await batch.commit();
console.log(`已提交第 ${i / chunkSize + 1} 批`);
}
}
batch操作的限制与容易忽略的细节
Firestore的batch并不是一个可以无限堆积写入的容器。根据官方约束，单次batch最多包含500次写入操作，写入、更新、删除都计入这个配额。超过500次操作时，commit()会直接报错。同时，单次batch的总数据量也有上限，每个文档的操作最大为1 MiB，整体batch大小通常控制在10 MiB以内。因此在实际项目中，即使数据只有几百条，也建议把分块上限设在400到450之间，给后续字段扩展留出缓冲。
另一个容易踩坑的点是同一文档在同一个batch中出现多次操作。如果对一个文档先执行set()，再执行update()，Firestore不会按顺序先后执行这两次操作，而是只保留最后一次操作的结果。这样设计可以避免客户端做复杂的冲突合并，但也意味着前面的调用被完全覆盖。如果某些逻辑依赖于第一次写入的字段，应该重新梳理数据，确保每个文档在一个batch中只出现一次。
还要注意，batch不支持读取操作。也就是说，不能在batch里先读取某个文档的当前值，再根据结果决定写入什么。凡是需要基于当前值做条件判断的写入，比如库存扣减、计数器自增、用户余额变动，都应该改用事务而不是batch。batch的定位是盲写：你已经知道要写什么，只需要把所有变更一次性提交。
batch和事务的适用边界
Firestore同时提供了runTransaction和writeBatch，很多开发者会把两者混淆。事务支持在回调中执行读操作，然后根据读到的内容修改数据。如果事务执行期间数据被其他客户端改动，Firestore会自动重试整个事务。而batch不读取数据、不做条件判断、也不重试，它只负责把一组确定的变更提交上去，速度更快，资源占用更少。
从行为上看，事务的典型示例是计数器自增。下面这段代码先读取文档中的count字段，然后在该值基础上加1。如果两个客户端同时执行，Firestore会通过重试保证最终计数不会少加。这种逻辑放在batch里根本无法实现，因为batch无法读取旧值。
import { runTransaction } from "firebase/firestore";
async function incrementCounter(db, docRef) {
await runTransaction(db, async (transaction) => {
const snapshot = await transaction.get(docRef);
if (!snapshot.exists()) {
throw new Error("文档不存在");
}
const currentCount = snapshot.data().count || 0;
transaction.update(docRef, { count: currentCount + 1 });
});
}
反过来，事务也不适合大批量盲写。事务回调执行次数越多，遇到写入冲突时重试的概率越高，一旦重试就会重新执行整个回调，带来额外读取和计算开销。例如导入1000条用户数据时，用事务逐条处理会非常慢，而用batch分三批提交则简单高效。判断依据很简单：如果写入逻辑不依赖当前数据库状态，优先使用batch；如果必须先读后写，使用事务。
真实项目中的分批策略与优化建议
批量导入、数据迁移、定时清理过期记录是batch最常见的三类场景。无论哪种场景，都建议将数据切成小批处理，不要试图一次提交所有内容。单批过大除了容易触发配额错误，还会在网络不稳定的情况下导致整批失败，增加重试成本。实践中每批400条是一个比较稳妥的值，如果单文档体积较大，比如包含长文本或富文本字段，还可以进一步降到200条甚至100条。
错误处理同样重要。commit()失败时，整批操作都会回滚，不会出现部分写入。捕获错误后可以先记录当前批次的起始索引，再根据索引重新处理该批数据。不要直接从头开始重跑，否则前面已经提交成功的数据会被重复写入。对于需要高并发写入的场景，可以使用Promise.all并行提交多个batch，但要注意Firestore的写入配额和客户端连接限制，避免同时发起过多请求触发限流。
如果项目同时使用Firebase Realtime Database，又希望在一次调用中修改多个路径，可以用它提供的多路径update()。虽然Realtime Database的多路径更新不是Firestore batch的完全替代品，它的原子性范围更小，也不支持删除多个独立节点，但对于简单的批量状态同步仍是一个可选方案。总体来说，只要数据存储在Firestore中，批量写入就应优先考虑writeBatch，用分块提交控制规模，用事务处理依赖读取的写入，两者配合能覆盖大多数数据变更需求。
Firebase数据库批量写入batch操作修改时间：2026-09-26 03:36:06