Next.js配置Apollo Client的AppSync订阅报TypeError如何排查

在Next.js框架前端项目中，初始化支持AWS AppSync订阅功能的Apollo Client实例后，程序运行抛出如下错误：

TypeError: Cannot read properties of undefined (reading 'subscriptionFailedCallback')

相关配置代码、依赖版本如下：

// graphql-client.js
const authClientConfig = {
  url: process.env.NEXT_PUBLIC_APPSYNC_GRAPHQL_ENDPOINT,
  region: process.env.NEXT_PUBLIC_REGION,
  auth: {
    type: "AMAZON_COGNITO_USER_POOLS",
    jwtToken,
  },
};
const link = ApolloLink.from([
  createAuthLink({
    url: authClientConfig.url,
    region: authClientConfig.region,
    auth: authClientConfig.auth,
  }),
  createSubscriptionHandshakeLink({
    url: authClientConfig.url,
    region: authClientConfig.region,
    auth: authClientConfig.auth,
  }),
]);

const FinedeedsAppClient = new ApolloClient({
  link,
  cache: new InMemoryCache(),
});

return FinedeedsAppClient;

// package.json 相关依赖
"aws-appsync-subscription-link": "^3.0.11",
"@apollo/client": "^3.6.8",
"apollo-link-http": "^1.5.17",
"aws-appsync-auth-link": "^3.0.7",
"apollo-link": "^1.2.14"

触发这个报错有两个核心原因：

1. createSubscriptionHandshakeLink调用方式错误：该API的标准双参数用法为「第一个参数传AppSync连接配置、第二个参数传处理普通Query/Mutation的HTTP Link实例」，当前代码仅传入了单个配置对象，函数内部执行订阅握手逻辑时，无法从链路上下文拿到预期的回调对象，直接读取subscriptionFailedCallback属性就会触发类型错误。
2. 依赖版本冲突：额外安装的apollo-link@1.2.14、apollo-link-http@1.5.17是适配Apollo Client 2.x的独立旧包，和@apollo/client@3.x内置的Link实现存在多实例冲突，会打断链路上下文的传递，进一步触发该问题。

• 第一步：清理冲突依赖，卸载适配旧版Apollo Client的独立Link包

  # npm 执行
  npm uninstall apollo-link apollo-link-http
  # yarn 执行
  yarn remove apollo-link apollo-link-http
  

• 第二步：修正Apollo链路组合逻辑，单独创建HTTP Link实例，按正确参数格式传入API，同时补充Next.js适配配置
  修正后的graphql-client.js代码如下：

  import { ApolloClient, InMemoryCache, ApolloLink, createHttpLink } from '@apollo/client';
  import { createAuthLink } from 'aws-appsync-auth-link';
  import { createSubscriptionHandshakeLink } from 'aws-appsync-subscription-link';
  
  const authClientConfig = {
    url: process.env.NEXT_PUBLIC_APPSYNC_GRAPHQL_ENDPOINT,
    region: process.env.NEXT_PUBLIC_REGION,
    auth: {
      type: "AMAZON_COGNITO_USER_POOLS",
      jwtToken,
    },
  };
  
  // 单独创建HTTP链路，处理普通查询、变更请求
  const httpLink = createHttpLink({ uri: authClientConfig.url });
  
  const link = ApolloLink.from([
    createAuthLink(authClientConfig),
    // 按双参数格式传入配置与HTTP Link实例
    createSubscriptionHandshakeLink(authClientConfig, httpLink)
  ]);
  
  const FinedeedsAppClient = new ApolloClient({
    link,
    cache: new InMemoryCache(),
    // 适配Next.js服务端渲染逻辑，避免服务端执行WebSocket订阅逻辑报错
    ssrMode: typeof window === 'undefined',
  });
  
  export default FinedeedsAppClient;
  

• 校验说明：当前使用的@apollo/client@^3.6.8、aws-appsync-auth-link@^3.0.7、aws-appsync-subscription-link@^3.0.11版本本身不存在兼容问题，清理冲突依赖、修正调用方式后即可正常运行订阅功能。

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