Next.js中Apollo GraphQL查询无法运行的问题排查

核心问题分析 #

从报错信息来看，useQuery无法获取Apollo Client实例，原因是**SearchPage不在ApolloProvider的组件树范围内**：你仅在Homepage（对应/路由）中用ApolloProvider包裹了组件，但SearchPage是独立路由/search的页面组件，跳转后新页面的组件树没有被ApolloClient实例覆盖。

修复方案（全局配置Apollo Client） #

在Next.js App Router中，正确的做法是在根布局中全局提供Apollo Client，确保所有路由下的组件都能访问到客户端实例。

1. 创建独立的Apollo Client实例文件 #

新建app/lib/apolloClient.ts：

import { ApolloClient, InMemoryCache } from "@apollo/client";

let apolloClient: ApolloClient<any>;

function createApolloClient() {
  return new ApolloClient({
    uri: "http://localhost:5000/graphql",
    cache: new InMemoryCache(),
  });
}

export function initializeApollo(initialState = null) {
  const _apolloClient = apolloClient ?? createApolloClient();

  // 服务端渲染/静态生成时合并初始缓存状态
  if (initialState) {
    const existingCache = _apolloClient.extract();
    _apolloClient.cache.restore({ ...existingCache, ...initialState });
  }

  // 仅在客户端缓存实例，服务端每次请求重新创建
  if (typeof window === "undefined") return _apolloClient;
  if (!apolloClient) apolloClient = _apolloClient;

  return _apolloClient;
}

2. 在根布局中全局注入ApolloProvider #

修改app/layout.tsx：

"use client";

import { ApolloProvider } from "@apollo/client";
import { initializeApollo } from "./lib/apolloClient";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const apolloClient = initializeApollo();

  return (
    <html lang="en">
      <body>
        <ApolloProvider client={apolloClient}>
          {children}
        </ApolloProvider>
      </body>
    </html>
  );
}

3. 移除Homepage中的重复Apollo配置 #

现在全局已经提供了Client，Homepage无需再重复初始化：

"use client";

import MainPageContainer from "./components/MainPageContainer";

function Homepage() {
  return <MainPageContainer />;
}

export default Homepage;

4. 修复SearchPage的客户端组件声明 #

useQuery是客户端钩子，必须在客户端组件中使用，给SearchPage添加客户端指令并完善状态处理：

"use client";

import { gql, useQuery } from "@apollo/client";

const SEARCH_QUERY = gql`
  query SearchByKeywords($keywords: String!) {
    searchedResponse(keywords: $keywords) {
      data {
        author
        description
        title
      }
    }
  }
`;

function SearchPage() {
  const test = "ufo";
  const { data, loading, error } = useQuery(SEARCH_QUERY, {
    variables: { keywords: test },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>查询错误：{error.message}</div>;

  return (
    <div>
      {data?.searchedResponse?.data?.map((item, index) => (
        <div key={index}>
          <h3>{item.title}</h3>
          <p>作者：{item.author}</p>
          <p>{item.description}</p>
        </div>
      ))}
    </div>
  );
}

export default SearchPage;

额外验证点 #

• 确认GraphQL服务端http://localhost:5000/graphql正常运行，且searchedResponse查询支持keywords变量并返回对应格式数据；
• 检查所有使用Apollo钩子的组件都添加了"use client";指令（Next.js App Router默认路由组件为服务器组件）。

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