Firebase 中 Auth 状态变更与用户文档更新的竞态问题解决方案

本文详解如何解决 firebase 登录后 `onauthstatechanged` 读取 firestore 用户文档时因本地缓存和未完成写入导致返回空/不完整数据的问题，推荐使用 `source: 'server'` 或监听 `haspendingwrites === false` 的实时快照。

在 Firebase 应用中，当调用 signInWithPopup 后立即执行 setDoc(..., { merge: true })，同时又在 onAuthStateChanged 回调中读取同一用户文档时，常会遇到「读到空对象」或「字段缺失」的现象——这并非逻辑错误，而是 Firestore SDK 的本地缓存 + 离线写入队列机制所致。

具体来说：

• setDoc 使用 { merge: true } 会触发一个异步写入操作，该操作先写入本地缓存（立即生效），再异步同步至服务器；
• onAuthStateChanged 触发后调用的 getDoc() 默认优先从本地缓存读取，此时若写入尚未完成同步，缓存中可能只有部分字段（甚至为空对象），且 snapshot.metadata.fromCache === true、snapshot.metadata.hasPendingWrites === true；
• 这正是你添加 setTimeout(3000) 后能读到完整数据的原因：延迟让写入大概率完成同步，缓存已更新。

✅ 推荐解决方案一：强制从服务器读取（简单可靠）
在 onAuthStateChanged 中显式指定 source: 'server'，跳过本地缓存，确保获取最终一致的数据：

import { getDoc, doc, getFirestore } from 'firebase/firestore';

export const initAuth = (): void => {
  auth.onAuthStateChanged(async (user) => {
    if (!user) return;

    try {
      const docRef = doc(getFirestore(), 'users', user.uid);
      // ? 关键：强制从服务器拉取最新快照
      const snapshot = await getDoc(docRef, { source: 'server' });

      if (snapshot.exists()) {
        console.log('✅ 完整用户文档:', snapshot.data());
      } else {
        console.log('⚠️ 用户文档不存在，可在此创建默认数据');
        await setDoc(docRef, { createdAt: new Date() }, { merge: true });
      }
    } catch (err) {
      console.error('❌ 读取用户文档失败:', err);
    }
  });
};

⚠️ 注意：source: 'server' 会增加网络延迟（无缓存），但在登录初始化场景下合理——用户首次进入应用，短暂等待（

✅ 推荐解决方案二：监听实时快照并等待写入完成（更健壮）
若需响应式体验（如加载状态）或处理频繁更新场景，可改用 onSnapshot 并过滤掉缓存/待写入状态：

import { onSnapshot, doc, getFirestore } from 'firebase/firestore';

export const initAuth = (): void => {
  auth.onAuthStateChanged((user) => {
    if (!user) return;

    const docRef = doc(getFirestore(), 'users', user.uid);

    // 监听实时快照，仅在满足条件时处理
    const unsubscribe = onSnapshot(docRef, (snapshot) => {
      const { fromCache, hasPendingWrites } = snapshot.metadata;

      // ✅ 仅当数据来自服务器且无待同步写入时才使用
      if (!fromCache && !hasPendingWrites) {
        if (snapshot.exists()) {
          console.log('✅ 最终一致的用户文档:', snapshot.data());
          // ? 此处可安全分发用户数据、更新全局状态等
        } else {
          console.log('⚠️ 文档仍不存在，触发初始化');
          // 可在此调用初始化逻辑（如设置默认字段）
        }
        unsubscribe(); // 一次性监听，用完即退
      }
      // 其他情况（fromCache || hasPendingWrites）静默忽略
    });
  });
};

? 关键要点总结：

• 不要依赖 setTimeout 做竞态修复——它不可靠（网络波动、设备性能差异会导致失效）；
• merge: true 本身无错，问题根源在于读写时机与缓存策略；
• source: 'server' 适合初始化读取（强调强一致性）；
• onSnapshot + metadata 适合需要响应式更新或复杂状态管理的场景；
• 若用户文档需严格初始化（如必填字段），建议在 signInAndUpdateUserObject 中直接写入必要字段，而非空对象：

  await setDoc(docRef, { 
    uid: user.uid, 
    email: user.email, 
    createdAt: new Date() 
  }, { merge: true });

通过以上任一方案，即可彻底规避 Auth 状态变更与 Firestore 文档读写的竞态问题，构建稳定可靠的用户数据流。