使用PersistQueryClientProvider时的React Query TypeScript类型错误排查

错误信息如下：

Type 'QueryClient' is missing the following properties from type 'QueryClient': logger, mountCount, ensureQueryData, getLogger ts(2739)
QueryClientProvider.d.ts(12, 5): The expected type comes from property 'client' which is declared here on type 'IntrinsicAttributes & PersistQueryClientProviderProps'

项目代码：

import React from "react";
import ReactDOM from "react-dom";
import "./index.css";
import App from "./App";
import { AuthProvider } from "./context/AuthContext";
import { BrowserRouter } from "react-router-dom";
import { QueryClient, QueryClientProvider } from "react-query"
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      cacheTime: 1000 * 60 * 60 * 24,
    },
  },
})

const persister = createSyncStoragePersister({
  storage: window.localStorage,
})

ReactDOM.render(
  <AuthProvider>
    <BrowserRouter>
      <PersistQueryClientProvider client={queryClient} persistOptions={{ persister }}>
        <App />
      </PersistQueryClientProvider>
    </BrowserRouter>
  </AuthProvider>,
  document.getElementById("root")
);

项目依赖版本：

{
  "name": "template-vite-react-ts-tailwind-v3",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "@tanstack/query-sync-storage-persister": "^4.32.0",
    "@tanstack/react-query-persist-client": "^4.32.0",
    "axios": "^1.4.0",
    "framer-motion": "^10.13.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-hook-form": "^7.45.2",
    "react-query": "^3.39.3",
    "react-router": "^6.14.2",
    "react-router-dom": "^6.14.2"
  },
  "devDependencies": {
    "@types/axios": "^0.14.0",
    "@types/react": "^17.0.33",
    "@types/react-dom": "^17.0.10",
    "@types/react-query": "^1.2.9",
    "@types/react-router": "^5.1.20",
    "@vitejs/plugin-react": "^1.0.7",
    "prettier": "^2.5.1",
    "prettier-plugin-tailwindcss": "^0.1.5",
    "typescript": "^4.4.4",
    "vitawind": "^2.2.4",
    "vite": "^2.7.2"
  }
}

错误原因 #

核心问题是版本不兼容：

• 你安装的@tanstack/react-query-persist-client和@tanstack/query-sync-storage-persister是v4版本，它们依赖的是@tanstack/react-query（v4版本的react-query已正式更名）。
• 但项目中实际安装的是旧版react-query（v3.39.3），两者的QueryClient类型定义差异极大，v4版本新增了logger、mountCount等属性，导致TypeScript类型校验失败。

解决方法 #

步骤1：替换依赖 #

卸载旧版react-query及对应类型包，安装与persist-client版本匹配的v4版@tanstack/react-query：

# 卸载旧依赖
npm uninstall react-query @types/react-query

# 安装同版本的v4 react-query
npm install @tanstack/react-query@^4.32.0

步骤2：修改代码导入 #

将原本从react-query导入的模块改为从@tanstack/react-query导入：

// 替换原导入语句
import { QueryClient, QueryClientProvider } from "react-query"
// 改为
import { QueryClient, QueryClientProvider } from "@tanstack/react-query"

步骤3：清理依赖缓存（可选） #

如果仍有类型报错，可删除依赖目录和锁文件后重新安装：

rm -rf node_modules package-lock.json
npm install

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