本地环境中Hot Chocolate GraphQL服务器WebSocket连接失败

问题梳理 #

已在ASP.NET Core应用中添加app.UseWebSockets()，HTTP请求可正常获取响应，但WebSocket连接失败：

• 使用wscat连接ws://localhost:7217/graphql/时提示「socket hang up」
• React Apollo Client连接ws://localhost:7217/graphql/ws时提示连接失败

排查步骤 #

1. 修正WebSocket端点路径 #

Hot Chocolate 13默认WebSocket端点为/graphql，而非/graphql/ws：

• 将Apollo Client的连接地址改为ws://localhost:7217/graphql
• 使用wscat测试时去除路径末尾斜杠，执行命令：

  wscat -c ws://localhost:7217/graphql
  

  可添加-d参数查看详细调试日志：

  wscat -c ws://localhost:7217/graphql -d
  

2. 检查GraphQL服务配置完整性 #

确保启动时正确配置订阅支持，示例代码如下：

// 注册GraphQL服务
builder.Services.AddGraphQLServer()
    .AddSubscriptionType<Subscription>() // 必须添加订阅类型
    .AddInMemorySubscriptions(); // 启用内存订阅存储

// 中间件顺序必须正确
app.UseWebSockets(); // 此语句需放在MapGraphQL之前
app.MapGraphQL();

3. 验证应用启动端口与协议 #

• 查看launchSettings.json中的applicationUrl，确认服务器实际监听端口为7217；若启用HTTPS，WebSocket地址需改为wss://localhost:7217/graphql
• 若React应用运行在不同端口，需配置CORS允许WebSocket跨域请求：

  builder.Services.AddCors(options =>
  {
      options.AddPolicy("WebSocketCors", policy =>
      {
          policy.AllowAnyOrigin()
                .AllowAnyHeader()
                .AllowAnyMethod()
                .AllowCredentials(); // WebSocket必须启用凭证支持
      });
  });
  app.UseCors("WebSocketCors");
  

4. 确认订阅类型定义存在 #

Hot Chocolate需存在有效订阅类型才能激活WebSocket端点，示例订阅类型代码：

public class Subscription
{
    [Subscribe]
    [Topic("sample-topic")]
    public string OnSampleMessage([EventMessage] string message) => message;
}

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