Firestore查询返回空数组但存在匹配数据的问题排查

我跟着Firehip的NextJS课程做项目时，遇到Firestore v9查询返回空数组的问题——无报错信息，查询语句也无拼写错误。已将课程中的旧版Firebase语法升级到v9，其余代码与课程一致，怀疑问题出在Firebase端。在Firestore控制台执行相同查询可正常获取数据，但代码中始终返回空数组。

相关代码 #

helperFunction.tsx #

export async function getUserWithUsername(username: string) {
    const q = query(
        collection(firestore, "users"),
        where("username", "==", username),
        limit(1)
    );
    const userDoc = (await getDocs(q)).docs[0];
    return userDoc;
}

index.tsx #

export async function getServerSideProps({ query: urlQuery }) {
    const { username } = urlQuery;

    const userDoc = await getUserWithUsername(username);

    let user: object = {};
    let posts: any[] = [];

    if (userDoc) {
        user = userDoc.data();

        const postsQuery = query(
            collection(getFirestore(), userDoc.ref.path, "posts"),
            where("published", "==", true),
            orderBy("createdAt", "desc"),
            limit(5)
        );

        posts = (await getDocs(postsQuery)).docs.map(postToJSON);
        console.log("posts in users page", posts);
    }

    return {
        props: { user, posts },
    };
}

export default function UserProfilePage({ user, posts }) {
    return (
        <main>
            <h1>User's page</h1>
            <UserProfile user={user} />
            <PostFeed posts={posts} />
        </main>
    );
}

终端输出 #

posts in users page []

Firestore控制台验证 #

在Firestore控制台执行相同查询（筛选published == true，按createdAt降序排序），可以正常获取到匹配的文档。

排查与解决方法 #

• 确认Firebase服务器端初始化配置
  服务器端（getServerSideProps运行在Node环境）需使用服务账号密钥完成Firebase初始化，而非客户端的API密钥配置。检查getFirestore()实例是否与helperFunction.tsx中的firestore实例一致，避免多实例导致的权限或连接问题。

• 校验查询路径正确性
  打印userDoc.ref.path确认路径格式为users/{userId}，拼接后的posts子集合路径是否与Firestore中实际路径完全一致（注意大小写敏感）。

• 检查复合索引是否存在
  组合使用where和orderBy需要对应的复合索引。即使控制台查询能成功，服务器端查询可能因索引缺失静默返回空数组。前往Firestore控制台“索引”页面，确认是否存在users/{userId}/posts集合下，published等于条件+createdAt降序的复合索引，缺失则手动创建。

• 验证数据类型匹配
  确保Firestore中published字段为布尔类型而非字符串，createdAt为时间戳类型而非字符串/数字，类型不匹配会导致查询无匹配结果。

• 添加错误捕获与日志
  在查询处增加try-catch捕获潜在静默错误，打印查询快照的文档数量辅助排查：

  try {
    const querySnapshot = await getDocs(postsQuery);
    console.log("匹配的文档数量:", querySnapshot.size);
    posts = querySnapshot.docs.map(postToJSON);
  } catch (error) {
    console.error("posts查询失败:", error);
  }
  

内容的提问来源于stack exchange，提问作者boryswnr