TanStack Query 完整教學：React 資料快取與伺服器狀態管理實戰指南

什麼是 TanStack Query？

TanStack Query（前身是 React Query）專門管理「伺服器狀態」——從遠端 API 抓回來的資料。它幫你解決：自動快取、背景更新、重新驗證、重試機制、請求去重複。搭配 React 效能優化指南效果很好。

安裝與基本設定

npm install @tanstack/react-query @tanstack/react-query-devtools

在根層級設定 QueryClient 和 QueryClientProvider，staleTime 和 gcTime 是最重要的設定。

useQuery：資料查詢核心

queryKey 是靈魂所在，決定快取身份。建議用陣列從大到小排列。queryFn 必須回傳 Promise。

const { data, isLoading } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
})

useMutation：資料異動操作

寫入、更新、刪除用 useMutation，需手動觸發。常見模式是在 onSuccess 裡呼叫 invalidateQueries。

快取策略與失效機制

staleTime：資料在多久內算新鮮。gcTime：快取在沒有元件使用時保留多久。手動控制：invalidateQueries、setQueryData、removeQueries。預取：prefetchQuery 讓導航更即時。

與 Next.js App Router 整合

Server Component 預取資料，用 HydrationBoundary 傳給 Client Component。參考 Next.js App Router 遷移指南和 React 19 新功能。

結語

導入 TanStack Query 後，資料相關程式碼減少約 40%。從小功能開始替換，你很快就會愛上它。