React Query设置initialData后queryFn不执行的原因咨询

我在使用React Query时需要设置默认数据，配置initialData后发现queryFn完全没被调用，连带着onSuccess回调也无法执行，useQuery返回的数据一直停留在initialData设置的初始值。

我的代码如下：

const getProducts = () => {
    console.log("from getProducts");
    //Fetch data
}

export const useProducts = () =>
    useQuery({
        queryKey: ["AllProducts"],
        cacheTime: Infinity,
        staleTime: Infinity,
        initialData: {
            products: [],
        },
        queryFn: () => getProducts(),
        onSuccess: (data) => {
            console.log("from onSuccess");
            // Do some stuff
        }
    })

奇怪的是console.log("from getProducts");和console.log("from onSuccess");都没有输出。我知道改用placeholderData替代initialData后功能正常，但想搞清楚出现这个现象的原因。

使用的React Query及开发者工具版本：

"@tanstack/react-query": "^4.29.12",
"@tanstack/react-query-devtools": "^4.29.12",

核心原因：initialData会被视为缓存的"新鲜数据" #

当你配置initialData时，React Query会把这个值直接存入对应queryKey的缓存中，再加上你设置的staleTime: Infinity，这条缓存数据会被永久标记为"新鲜（fresh）"状态。

React Query的查询触发逻辑是：只有缓存中没有对应数据，或者数据处于"过时（stale）"状态时，才会调用queryFn获取最新数据。而你这里缓存已经有了initialData提供的新鲜数据，所以完全不会触发后台请求。

initialData和placeholderData的本质区别 #

• initialData：属于缓存的一部分，会被持久化到缓存中，后续查询优先使用它，直到数据超过staleTime变陈旧。
• placeholderData：只是临时占位数据，不会写入缓存，不管有没有设置staleTime，React Query都会正常调用queryFn拉取真实数据，同时在数据返回前用占位数据渲染UI。

你设置的staleTime: Infinity进一步固化了这个行为——缓存数据永远不会过时，所以queryFn永远没有执行的机会。

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