如何解决NestJS GraphQL Subscription(graphql-ws)的RangeError: Invalid Websocket frame报错

AI 小北

2026-9-29

报错根本原因

这个RangeError: Invalid Websocket frame: invalid payload length 126报错是NestJS v8内置的GraphQL Subscription依赖栈的兼容性缺陷导致：

NestJS v8的@nestjs/graphql v9版本与graphql-ws v5.x版本的websocket帧解析逻辑存在冲突
当客户端发送的WebSocket payload长度刚好落在126字节的扩展长度阈值区间时，框架内置的帧校验逻辑未正确处理扩展长度字段，直接抛出非法帧错误
该错误没有被NestJS内置的异常过滤器捕获，会直接触发Node.js进程未捕获异常，导致服务宕机

解决方案

按优先级从高到低可选以下几种方式：

方案1：升级依赖到修复版本（推荐）

将相关依赖升级到已修复该问题的版本即可，升级后无需修改业务代码：

@nestjs/graphql 升级到v10.0.0及以上
@nestjs/platform-express（或fastify对应的平台包）升级到v8.4.0及以上
graphql-ws 升级到v5.9.0及以上

方案2：添加全局WebSocket错误捕获（适合无法升级大版本的场景）

如果当前业务暂不支持升级NestJS大版本，可以在服务启动逻辑中添加WebSocket连接层面的错误监听，拦截未捕获的帧错误避免进程崩溃：

// main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const httpServer = app.getHttpServer();

  // 监听WebSocket升级请求，给每个连接添加错误处理
  httpServer.on('upgrade', (_, socket) => {
    socket.on('error', (err) => {
      // 拦截无效帧错误，直接销毁异常连接，不抛出到进程
      if (err.message.includes('Invalid Websocket frame: invalid payload length 126')) {
        socket.destroy();
        return;
      }
      console.error('WebSocket连接异常:', err);
    });
  });

  await app.listen(3000);
}
bootstrap();