NextJS+Pocketbase用react-query的useMutation报错：this.client.defaultMutationOptions is not a function

问题原因 #

这个错误的核心原因是React Query的客户端实例没有在组件树中正确配置，导致useMutation无法访问到有效的QueryClient上下文。在Next.js App Router（使用"use client"指令）的场景下，必须确保上层组件已通过QueryClientProvider提供QueryClient实例。

解决步骤 #

1. 确认依赖版本 #

确保安装的是最新版的TanStack React Query（原react-query已迁移到@tanstack/react-query）：

npm install @tanstack/react-query
# 或
yarn add @tanstack/react-query

2. 在根组件中配置QueryClientProvider #

以Next.js App Router为例，修改app/layout.tsx（需添加"use client"指令，因为涉及客户端状态管理）：

"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactNode } from "react";

const queryClient = new QueryClient();

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
      </body>
    </html>
  );
}

3. 修正useLogin自定义Hook #

确保login函数逻辑正确，同时规范useMutation的调用方式：

"use client";
import pb from "@/lib/pocketbase";
import { useMutation } from "@tanstack/react-query";

export default function useLogin() {
  async function login({ email, password }: { email: string; password: string }) {
    // 返回认证数据，方便后续业务处理
    return await pb.collection("users").authWithPassword(email, password);
  }

  return useMutation({
    mutationFn: login,
    // 可选：添加成功/失败回调便于调试
    onSuccess: (data) => {
      console.log("登录成功", data);
    },
    onError: (error) => {
      console.error("登录失败", error);
    },
  });
}

额外说明 #

如果使用的是旧版react-query（而非@tanstack/react-query），配置逻辑类似，但导入路径需改为react-query。另外，所有使用useMutation/useQuery的组件必须包裹在QueryClientProvider范围内，否则会持续出现上下文缺失类错误。

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