本文详解如何解决 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 文档读写的竞态问题，构建稳定可靠的用户数据流。
