NestJS GraphQL使用graphql-ws实现订阅连接失败该如何解决？

算力阿峰

2026-10-4

核心错误原因

服务端报错是因为客户端发送的WebSocket子协议是旧版subscriptions-transport-ws使用的graphql-ws，而新的graphql-ws库只支持graphql-transport-ws子协议，二者不兼容。你使用的默认GraphQL Playground默认走旧版子协议，是报错的直接诱因。

修复步骤

第一步：修正GraphQLModule配置，移除冲突项并配置Playground的订阅协议
删掉installSubscriptionHandlers配置项（该配置为旧版subscriptions-transport-ws专属，和新协议冲突），同时给Playground指定使用新版传输协议，参考配置如下：

GraphQLModule.forRoot({
  autoSchemaFile: true,
  sortSchema: true,
  playground: {
    subscriptionEndpoint: 'ws://localhost:8880/graphql',
    settings: {
      // 关键配置：指定Playground使用graphql-ws的新协议
      'subscriptions.transport': 'graphql-ws',
      'request.credentials': 'include'
    }
  },
  subscriptions: {
    'graphql-ws': {
      path: '/graphql'
    }
  },
})

第二步：确认graphql-ws依赖已安装到生产依赖中，执行安装命令：
```
npm install graphql-ws
```
第三步：自定义客户端/测试工具适配
如果你使用自定义前端客户端或者第三方WebSocket测试工具，需要手动指定请求的WebSocket子协议为graphql-transport-ws；前端项目需要将订阅客户端从subscriptions-transport-ws替换为graphql-ws的官方客户端实现。
第四步：兼容新旧客户端（可选）
如果需要同时支持旧版subscriptions-transport-ws的客户端，可以保留两个传输配置：
```
subscriptions: {
  'subscriptions-transport-ws': true,
  'graphql-ws': true
}
```
第五步：端口路径校验
确认服务启动端口为8880，GraphQL接口没有配置额外全局前缀，若有前缀需要同步修改WebSocket连接路径。