本地WebSocket服务器连接报错：SSL版本错误与响应200排查

错误分析 #

• wss://连接报错SSL版本问题：服务器未正确配置TLS证书，或客户端与服务器TLS协商失败；添加withoutTls后应使用ws://连接，此错误可忽略。
• ws://返回200：核心问题是WebSocket路由未正确触发协议升级，服务器将请求当作普通HTTP请求处理，返回200响应。

排查与修复步骤 #

1. 确认WebSocket路由定义正确 #

http4s中必须使用ws方法定义WebSocket端点，而非普通GET路由。示例正确写法：

import org.http4s._
import org.http4s.dsl.io._
import org.http4s.websocket.WebSocketFrame
import fs2.Stream

val helloWebSocket = HttpRoutes.of[IO] {
  // 匹配路径并返回WebSocket流
  case GET -> Root / "hello" / name =>
    ws(Stream.emit(WebSocketFrame.Text(s"Hello, $name!")))
}

如果路由是普通Ok("xxx")，必然返回200，不会触发WebSocket升级。

2. 确保服务器正确挂载WebSocket路由 #

需要将WebSocket路由与其他HTTP路由组合，避免被覆盖：

import org.http4s.ember.server.EmberServerBuilder
import cats.effect._

object Main extends IOApp {
  override def run(args: List[String]): IO[ExitCode] = {
    // 组合WebSocket路由与普通HTTP路由
    val allRoutes = helloWebSocket <+> HttpRoutes.of[IO] {
      case GET -> Root => Ok("Hello World!")
    }

    EmberServerBuilder.default[IO]
      .withHostname("localhost")
      .withPort(8080)
      .withoutTls() // 纯HTTP模式，仅支持ws://连接
      .withHttpApp(allRoutes.orNotFound)
      .build
      .use(_ => IO.never)
      .as(ExitCode.Success)
  }
}

3. 验证路径匹配准确性 #

客户端请求路径必须与服务器路由完全匹配：

• 若路由为/hello/:name（动态参数），客户端需使用具体名称，如ws://localhost:8080/hello/alice，而非/hello/name。
• 用curl验证路由：执行curl http://localhost:8080/hello/yourname，若返回200，说明路由未正确配置为WebSocket；若返回HTTP/1.1 101 Switching Protocols，则路由配置正确。

4. 若需wss://连接（加密） #

不能使用withoutTls，必须配置TLS证书：

EmberServerBuilder.default[IO]
  .withHostname("localhost")
  .withPort(8080)
  .withTlsFromFile("/path/to/your/cert.pem", "/path/to/your/key.pem")
  .withHttpApp(allRoutes.orNotFound)
  .build

无证书情况下使用wss://必然触发SSL握手错误，需先生成自签名证书用于测试。

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