Node.js用ws库搭建WebSocket服务客户端连接报SSL版本错误如何解决

问题根因 #

该报错与npm、Node.js版本升级无关，核心是WebSocket协议不匹配导致的SSL握手失败。

你后端用http模块创建的是普通未加密的HTTP服务，仅支持ws（未加密WebSocket）协议访问，但客户端使用wss://前缀发起连接，wss协议要求服务端必须配置SSL证书走TLS加密传输，服务端未做SSL配置的情况下无法解析TLS握手请求，就会抛出ssl3_get_record:wrong version number的错误。

解决方案 #

方案1：开发环境（无需加密传输） #

直接修改客户端连接地址的协议前缀即可，将wss改为ws：

// 修改前
const ws = new WebSocket("wss://localhost:8080/")
// 修改后
const ws = new WebSocket("ws://localhost:8080/")

方案2：生产环境（需要加密传输） #

修改服务端代码，使用https模块替代http模块并配置SSL证书：

import { createServer } from "https"
import { readFileSync } from "fs"
import { WebSocketServer } from "ws"

// 替换为你的SSL证书文件路径
const options = {
  cert: readFileSync("/path/to/ssl_cert.pem"),
  key: readFileSync("/path/to/ssl_key.pem")
}

const server = createServer(options)
const wss = new WebSocketServer({ server })

server.listen("8080", () => {
  console.log("wss服务已启动，监听端口8080")
})

wss.on("connection", (ws, req) => {
  ws.on("close", () => console.log("connection closed"))
})

注意：本地开发测试wss时如果使用自签证书，需要先手动在浏览器访问https://localhost:8080，将自签证书加入系统信任列表后才能正常连接。

额外优化建议 #

你当前客户端的WebSocket实例是在组件外部全局创建的，Next.js热更新时会重复创建连接且不会自动销毁，建议将实例创建逻辑移入useEffect并添加销毁回调：

import WebSocket from 'isomorphic-ws'
import {useEffect} from 'react'

const Page = () => {
  useEffect(() => {
    const ws = new WebSocket("ws://localhost:8080/")
    ws.onopen = () => {
      console.log("connection open")
    }
    // 组件卸载时主动关闭连接
    return () => {
      ws.close()
    }
  }, [])

  return <div></div>
}
export default Page

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