Firestore使用setDoc带merge更新部分字段后，getDocFromServer返回部分对象而非完整对象的问题排查

看起来你遇到了一个很典型的缓存与实时数据同步的问题，结合你的描述、代码和流程，我来帮你拆解可能的原因和解决思路：

一、最可能的根源：TanStack Query 缓存未及时失效 #

你说排除了TanStack Query的影响，但从现象来看——mutation成功后跳转首页，返回部分字段，过会儿或导航后才显示完整数据——这完全符合Query的缓存策略：

• 当你执行initUser这个mutation时，它的返回值或者内部处理可能已经把部分用户对象存入了Query的缓存。
• 跳转到首页后，useUser查询会优先返回缓存里的旧数据（也就是那部分字段），同时在后台悄悄重新获取最新数据。
• 等后台拿到完整数据后，Query才会更新缓存并触发界面刷新，这时候你就能看到完整的用户对象了。

哪怕你的getUser用了getDocFromServer绕过Firebase本地缓存，但TanStack Query的缓存是独立的，它会先返回自己的缓存，除非你主动让它失效。

验证&修复方式： #

在initUser.mutate的onSuccess回调里，手动失效对应的用户查询，强制Query重新去Firestore获取最新数据：

// 记得先导入queryClient
import { useQueryClient } from '@tanstack/react-query';

// 在组件内获取queryClient
const queryClient = useQueryClient();

// 然后在mutation的onSuccess里添加
initUser.mutate(
  { 
    uid: cred.user!.uid!, 
    email: cred.user.email!, 
    displayName: cred.user.email!.split('@')[0], 
    isActive: true, 
    courseProgress: [] 
  },
  {
    onSuccess: () => {
      setIsLoading(false);
      // 失效该用户的查询缓存，强制重新获取
      queryClient.invalidateQueries({ queryKey: ['user', cred.user!.uid!] });
      router.push('/(drawer)');
    }
  }
);

二、Firestore merge操作的逻辑确认 #

先看你的putUser代码逻辑：

if (merge && user.progress.length === 0) {
  const { progress, ...rest } = user;
  data = rest;
}
await setDoc(userRef, data, { merge: merge });

这个逻辑本身是对的：当merge为true且progress为空时，去掉progress字段再执行merge更新，避免覆盖Firestore中已有的progress数据。

• 如果是新用户：Firestore里没有该文档，merge:true会创建只包含传入字段的文档（也就是minimal fields），这时候请求完整对象本来就只有这些字段——但你说远程已有完整字段，所以这个情况不适用。
• 如果是已有用户：merge:true只会更新你传入的字段，不会删除原有字段，所以Firestore里的文档肯定是完整的。这时候如果getDocFromServer返回部分字段，99%是缓存的锅。

三、检查getUser函数的字段读取 #

你的getUser是手动构造返回对象的：

const ud = {
  uid: userDoc.id,
  email: data.email,
  displayName: data.displayName,
  isActive: data.isActive ?? true,
  progress: data.progress || []
};

建议你先打印Firestore返回的原始数据，确认服务器端的文档到底有没有完整字段：

const userDoc = await getDocFromServer(userRef);
if (!userDoc.exists()) { /* ... */ }
const data = userDoc.data();
console.log('Firestore原始返回数据:', data); // 打印完整数据，看是否包含所有字段

如果这里的data是完整的，那问题出在你构造ud的逻辑；如果data本身就是部分字段，那再回到缓存的问题排查。

四、为什么createIfNotExist能work？ #

你提到的createIfNotExist workaround有效，是因为这个函数只有在文档不存在时才写入数据——如果文档已存在（也就是你说的远程已有完整字段的情况），它不会执行任何写入操作，自然不会触发TanStack Query的缓存更新，首页的查询会直接去获取服务器的完整数据，而不是返回缓存的部分对象。

总结 #

核心问题大概率是TanStack Query的缓存未及时失效，导致首页查询先返回了mutation留下的部分对象缓存。只要在mutation成功后手动失效对应的查询，就能让首页直接获取最新的完整用户数据。

内容来源于stack exchange