Firestore：如何创建自定义ID文档且仅当文档不存在时执行？

核心解决方案：setDoc配合断言选项 #

Firestore的setDoc API可以通过设置断言选项，实现仅当文档不存在时创建，存在则直接失败的原子操作，无需提前读取文档。

代码示例

import { doc, setDoc } from "firebase/firestore";
import { db } from "./your-firebase-config"; // 替换为你的Firestore实例路径

async function createDocWithCustomId(collectionName, docId, data) {
  const targetDoc = doc(db, collectionName, docId);
  
  try {
    // 关键：添加assert选项，要求文档必须不存在
    await setDoc(targetDoc, data, {
      assert: { exists: false }
    });
    console.log("文档创建成功");
    return true;
  } catch (err) {
    // 捕获文档已存在的错误
    if (err.code === "failed-precondition") {
      console.log("文档已存在，操作终止");
    } else {
      console.error("创建失败:", err);
    }
    return false;
  }
}

关键说明

• 这是单一原子操作：所有逻辑由Firestore服务器端验证，无需先读再写，避免并发冲突。
• assert: { exists: false }：明确告诉Firestore，只有目标文档不存在时才执行写入，否则抛出failed-precondition错误。
• 模拟addDoc的逻辑：addDoc本质是Firestore自动生成唯一ID后调用setDoc，你只需替换成自定义ID+上述断言选项，就能实现相同的“不存在则创建”的原子性，且满足存在则失败的需求。

兼容旧版SDK的备选方案（事务实现） #

如果你的Firebase SDK版本不支持assert选项，可以用事务实现同样的逻辑（依然是原子操作）：

import { doc, runTransaction } from "firebase/firestore";
import { db } from "./your-firebase-config";

async function createDocWithCustomId(collectionName, docId, data) {
  const targetDoc = doc(db, collectionName, docId);
  
  try {
    await runTransaction(db, async (tx) => {
      const docSnap = await tx.get(targetDoc);
      if (docSnap.exists()) {
        throw new Error("doc_already_exists");
      }
      tx.set(targetDoc, data);
    });
    console.log("文档创建成功");
    return true;
  } catch (err) {
    if (err.message === "doc_already_exists") {
      console.log("文档已存在，操作终止");
    } else {
      console.error("创建失败:", err);
    }
    return false;
  }
}

内容的提问来源于stack exchange，提问作者touch my body