Apollo Server无Socket连接：NextJS前端GraphQL订阅WebSocket连接失败

1 服务端配置排查 #

• 确认是否在Apollo服务端正确启用了订阅支持：Type-GraphQL搭配Apollo Server时，需要额外安装subscriptions-transport-ws或graphql-ws依赖，且Apollo Server 3.x及以上版本默认不内置订阅能力，需要手动注册WebSocket处理器，不能仅启动普通HTTP GraphQL服务。
• 确认服务端WebSocket监听路径和前端配置一致，默认路径为/graphql，如果自定义了路径需要同步修改前端wsLink的uri参数。
• 确认8080端口无占用、服务端进程正常启动，可以先用WebSocket测试工具直接连接ws://localhost:8080/graphql验证链路是否通顺。

2 跨域与身份校验配置排查 #

• 你在HttpLink中配置了credentials: "include"，但WebSocket默认不会自动携带Cookie等身份凭证，如果服务端对订阅接口也做了身份校验，需要在wsLink的配置中新增凭证传递逻辑：

const wsLink = typeof window !== 'undefined' ? new WebSocketLink({
    uri: `ws://localhost:8080/graphql`,
    options: {
      reconnect: true,
      // 传递连接凭证
      connectionParams: {
        credentials: 'include'
      }
    }
  }) : null;

• 确认服务端CORS配置放开了WebSocket的跨域请求：NextJS默认运行在3000端口，和服务端8080端口属于跨域场景，需要在服务端CORS规则中添加前端域名的允许规则，WebSocket握手阶段会触发CORS校验。

3 客户端配置排查 #

• 确认客户端和服务端的订阅协议兼容：如果服务端使用的是新的graphql-ws库，客户端不能使用旧的subscriptions-transport-ws对应的WebSocketLink，需要替换为配套的GraphQLWsLink，两者协议不兼容会直接导致握手失败。
• 如果你使用的是NextJS 13及以上的App Router版本，process.browser已经被废弃，建议替换为typeof window !== 'undefined'来判断客户端环境，避免wsLink实例化逻辑异常。
• 确认getMainDefinition是从@apollo/client/utilities正确导入，split函数的链路拆分逻辑无错误。

4 其他排查项 #

• 关闭本地代理、VPN、浏览器广告拦截类插件，这类工具可能会拦截WebSocket请求。
• 重启NextJS开发服务，开发模式下热重载可能会导致WebSocket连接重复实例化引发异常。

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