简介这份WebSocket测试工具包面向需要进行实时通信调试的前端与后端开发者用来验证客户端与服务器之间的握手流程、帧格式、心跳检测、安全性以及高并发下的性能表现适用于在线聊天、游戏对战、股票行情、协作编辑等低延迟场景。包内共19个文件既有可直接打开的HTML在线测试页面和相关JS、CSS脚本也有GIF操作演示和PNG界面截图同时提供Windows下可执行的WebSocket客户端测试工具v4.20免费版、简易服务器配套程序、依赖的DLL动态库并附带RAR示例包、C#使用方法和服务器说明文档整体压缩包仅2.87MB部署非常轻量。目前已有382人学习下载。这些内容不仅支持直接运行并收发帧消息还能引导开发者从HTTP升级握手开始逐步理解文本帧与二进制帧的区别、Ping/Pong心跳机制和WSS安全连接适合在开发排错、协议学习或教学演示中作为快速实验环境。1. WebSocket 测试工具别等服务端把问题藏起来先把这三层看明白之前联调一个长连接项目A 同学信誓旦旦说服务端把推送协议改了客户端一条消息都收不到后端同事翻日志也说没毛病。最后把两边的抓包文件放到一起看才发现测试客户端收到的数据帧 FIN 位是 0工具把它当成一条完整消息直接丢掉了一半。从那以后我养成了习惯任何 WebSocket 测试工具先确认它能不能看到握手、看到帧、看到关闭码这三层。这份资源就是一套以命令行命令加 Python 脚本为主的 WebSocket 测试工具箱覆盖连接握手检查、收发帧观察、心跳与重连模拟、并发冒烟和回放留证解决的是服务端连不上、连接莫名断开、并发超时、中文乱码这些实际联调问题。适合后端开发、写长连接测试的同行以及要验收网关和代理超时策略的运维同事。2. 握手、帧与状态码判断一个测试工具是否靠谱的三条基准2.1 握手不是 GET先看工具能不能拆出 Upgrade 请求WebSocket 的连接建立本质是一场 HTTP 升级不是一条普通的 GET。客户端发出去的头里会带Connection: Upgrade、Upgrade: websocket、Sec-WebSocket-Version: 13还有一个随机生成的Sec-WebSocket-Key。服务端如果认可会回101 Switching Protocols并在Sec-WebSocket-Accept里返回基于这个 Key 计算的摘要。很多现成工具只给你一个“已连接”的提示看不到这些一旦遇到反向代理拦截 Upgrade、服务端路由不匹配问题就很容易被藏起来。我一般会在命令行里先用 curl 完整打一次握手把服务端的响应头和状态码摊开看。比如对一个部署在内网的测试服务curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ -H Origin: http://127.0.0.1 \ http://10.0.0.8:8080/wsSec-WebSocket-Key的值可以随便生成只要符合 base64 格式就行服务端计算Sec-WebSocket-Accept时会用到它。如果返回101握手这一层就是通的如果返回400 Bad Request先看响应体里有没有提示缺少哪个头有些网关会强制要求客户端带Origin或Sec-WebSocket-Protocol如果回来的是426 Upgrade Required多半是代理配置把Connection头过滤掉了这种情况换测试工具没用得先改网关。一个靠谱的测试工具应该能在日志里显示握手请求头、响应头和状态码。如果工具界面只有一个“连接成功”遇到握手类问题就只能靠抓包定位效率会低很多。我在评估一个工具值不值得用进项目时会先跑一遍这条 curl 命令确认服务端握手行为是符合常规的再拿工具去连同一个地址对比两者展示的信息量。2.2 帧内 opcode 与掩码只看消息收发会漏掉分片问题WebSocket 建立之后数据不是按“一条消息”整体传的而是切成一帧一帧走。每帧第一个字节里最高位是FIN表示这是不是消息的最后一段低 4 位是opcode0x1表示文本0x2表示二进制0x9是 ping0xA是 pong0x8是关闭。客户端发出的帧必须带掩码也就是MASK位要置 1服务端返回的帧不能带。测试工具如果只把完整消息拿出来给你看分片和掩码这些问题就等于被过滤了。我写过一个最小帧构造代码用来验证测试工具内部处理是否符合协议import os, struct payload {\action\:\ping\}.encode(utf-8) mask_key os.urandom(4) masked bytes(b ^ mask_key[i % 4] for i, b in enumerate(payload)) frame bytearray() frame.append(0x81) # FIN1, opcode0x1, 文本帧 # 客户端帧必须带 MASK 位即长度字节最高位置 1 if len(payload) 126: frame.append(0x80 | len(payload)) elif len(payload) 65536: frame.append(0x80 | 126) frame.extend(struct.pack(H, len(payload))) else: frame.append(0x80 | 127) frame.extend(struct.pack(Q, len(payload))) frame.extend(mask_key) frame.extend(masked)这段代码的要点有几个。第一0x81的二进制是1000 0001FIN1且opcode1代表“这是完整的一帧文本消息”如果服务端把大消息拆成多帧第一帧的FIN会是 0只有最后一帧的FIN才是 1。第二客户端帧必须置MASK位也就是长度字节的最高位要置 1否则服务端会直接断开连接。第三负载长度小于 126 用的是短编码126 到 65535 之间用 2 字节扩展长度再大用 8 字节边界值 126 和 65535 是最容易测出工具 bug 的地方。如果你的测试工具能在日志里把分片拼接情况或原始十六进制帧显示出来处理“服务端推送大 JSON 时客户端丢帧”这类问题会少踩很多坑。我在模拟项目X里就遇到过服务端把一条几十 KB 的推送分成 20 多个帧发出来工具没拼接业务侧就永远缺最后一个分片。2.3 状态码 1000-1011断开原因写在编号里连接关闭也不是只有“断了”这一个状态。正常的关闭流程会走 close 帧里面带一个状态码异常断开则常常什么都没有。工具能不能显示这个编号直接决定定位方向。状态码含义常见触发场景1000正常关闭双方协商一致比如客户端主动 close1001服务端离开/重启代码发布、实例滚动重启1006异常关闭TCP 层被断开没有 close 帧1008策略违规鉴权失败、消息格式不符合协议1009消息过大超过服务端配置的 maxPayload1011服务端内部错误业务异常服务端直接终止连接这里最值得警惕的是1006。它不是一个会在 close 帧里出现的编号而是客户端在底层 TCP 连接断开后发现一直没有收到 close 帧自己报出来的兜底值。实际含义是“连接没了但双方没走正常关闭流程”最常见的元凶是代理或网关的空闲超时把底层连接掐了。排查这种问题经验靠不住必须结合抓包和两端日志对齐时间线回头我会在避坑章节写一个现场复现。一个合格的测试工具至少要在断开时把收到的 close code 打印出来而不是只显示“连接关闭”四个字。配合抓包看一眼是 FIN 还是 RST能很快判断是服务端主动关还是中间链路被切断。工具如果连状态码都舍不得展示建议趁早换掉。3. 从命令行到脚本把 WebSocket 测试跑出可复现结果的三个台阶3.1 命令行冒烟三秒确认端点活着联调开始前我会先用命令行客户端做一次最小冒烟确认服务端端口在监听、握手能通、默认消息路径没错。常见做法是用 wscat 这种交互式命令行工具连接之后手动输入一条 JSON看服务端回不回 pong。它能实时显示收发消息对排查“服务端到底收没收到”这种问题特别直接。wscat -c ws://127.0.0.1:8080/ws?envtesttokendemo \ -H Origin: http://127.0.0.1连接成功后手动输入{action:ping,ts:1620000000}回车期望回包是{action:pong}。-c是指定连接地址-H是附加请求头有的服务端会校验Origin不加这个头会握手失败wss 场景下加-n参数可以跳过证书校验但只建议在本地测试环境用。如果 wscat 一进去就报Unexpected response code: 404先看路径对不对再确认网关有没有把/ws转发到后端。除了 wscatwebsocat 也支持管道模式可以把系统命令的输出直接通过 WebSocket 发出去方便做流式接口冒烟但它偏向流式测试日常联调我还是习惯用 wscat。命令行冒烟的意义在于快速排除“网络通不通、路径对不对、服务端是否启动”这类低级问题。三秒能确认的连通性不要等到脚本跑完才暴露。我每次换环境第一件事就是跑这条命令确认能连上再谈协议和业务功能。3.2 Python 脚本压测并发连接与断线重连冒烟通过后真正的压力在脚本化测试。WebSocket 服务最常见的返工点不是单连接功能不对而是并发一上来就超时、断线、内存涨。我常用 websocket-client 库写并发放包脚本先跑小并发验证功能再逐步加量。import json, threading, time import websocket start time.time() results [] def client(idx, url, results): try: ws websocket.create_connection(url, timeout10) ws.send(json.dumps({action: ping, client: idx})) resp json.loads(ws.recv()) results.append((idx, resp.get(action), time.time())) ws.close() except Exception as e: results.append((idx, ERROR, repr(e))) url ws://127.0.0.1:8080/ws?envtest threads [] for i in range(200): t threading.Thread(targetclient, args(i, url, results)) threads.append(t) t.start() for t in threads: t.join() ok [r for r in results if r[1] ! ERROR] print(fconnected{len(ok)}/200, elapsed{time.time()-start:.2f}s)脚本的逻辑是每个线程负责建立一条连接发送一条 ping等待一条 pong记录结果后关闭。timeout10指握手和收包的总超时超过这个秒数直接抛异常计入 ERROR。这里的results.append在线程里是原子操作小规模并发下不会丢数据但 200 个线程在本地验证小规模并发足够要跑几千连接不建议继续用线程堆GIL 和线程切换开销会让结果失真。这时候我更倾向于用 asyncio 或换一个专门压测长连接的工具脚本侧只保留功能验证和场景模拟。跑完看两个数成功连接数和耗时。如果成功连接数明显低于预期先检查服务端有没有 accept 失败日志再看客户端是不是撞上了 ulimit 限制具体处理放到避坑章节展开。3.3 配置文件驱动URL、心跳、鉴权与期望回包脚本最怕写死。换一套环境就要改代码很容易出现“上线前改漏了 URL结果测了别的环境”的乌龙。我一般会把场景参数抽到 JSON 配置文件里脚本只负责读取和执行这样同一份脚本可以在多个环境之间复用。{ url: ws://127.0.0.1:8080/ws?envtest, headers: {Authorization: Bearer demo-token}, heartbeat: 30, timeout: 10, expect: {action: pong} }import json, websocket with open(case.json, r) as f: cfg json.load(f) ws websocket.create_connection( cfg[url], timeoutcfg[timeout], headercfg[headers] )这个配置文件里url是整个测试入口headers里放鉴权和自定义头heartbeat是心跳间隔timeout是单次收发超时expect是断言用的期望回包。配置化的好处是同一套脚本在开发、测试环境之间切换只需要换 JSON。对于带 token 的接口token 走环境变量注入会比写死在文件里更安全本地测试无所谓但 CI 里跑的时候我习惯用${WS_TOKEN}这种占位符。这个台阶过完之后你的测试已经从“能连上”变成“可重复”。接下来就是调参数让结果接近线上真实链路这部分玄学最少坑最多。4. 参数调优心跳、超时、重连与鉴权头别凭感觉4.1 心跳与空闲超时谁先断开谁有理长连接最常用的心跳方式有两种。第一种是底层 ping/pong 控制帧客户端定时发 ping服务端回 pong第二种是业务层自己约定一条 JSON 消息双方收到后回一条确认。用哪种取决于服务端实现但不管哪一种核心参数都是服务端的空闲超时。我见过不少服务端把空闲超时设为 60 秒而测试脚本的心跳间隔设成 90 秒结果就是服务端到点没收到任何数据直接把连接断开客户端看到 1006。要避免这个局面测试脚本里的心跳间隔必须小于服务端空闲超时的一半这是我从多次翻车里总结出来的经验值。如果服务端允许配参数把空闲超时调到 120 秒心跳走 30 秒一次留出的余量足够扛住网络抖动。在 websocket-client 里底层控制帧 ping 可以直接用ws.ping()触发由库自动走控制帧业务层心跳则要自己按时间戳发 JSON。真实联调中这两种心跳可能同时存在工具要把它们区分开。如果测试工具把所有心跳消息都当成业务数据打点日志会非常脏回放时也会干扰排障。我写脚本时会把心跳收发单独打一个 debug 级别的日志和业务消息分开。另外要注意有些网关的空闲超时只认代理层转发的流量业务层心跳即使一直在发只要没经过代理转发连接照样会被掐掉这种只看字节数就能判断。4.2 重连退避别让测试客户端变成误伤源服务端重启、网络闪断、代理空闲断开都会触发客户端重连。如果重连逻辑写得太激进比如断开后立即重试并且不设上限一个测试脚本就能把刚起来的服务端活活打成半死不活的状态。这不是玩笑我见过模拟项目X里一个监控脚本每 200 毫秒重试一次把服务端连接线程池打满服务端进程直接拒绝新连接。指数退避是长连接客户端的标准做法重连间隔按指数增长同时设一个最大重试次数超过就放弃并报警避免脚本在 CI 里无限刷日志。import time, websocket url ws://127.0.0.1:8080/ws max_retries 10 retry 0 while retry max_retries: try: ws websocket.create_connection(url, timeout10) break except Exception: wait min(30, 1 retry) # 1s, 2s, 4s ... 封顶 30s retry 1 time.sleep(wait)这段逻辑说明两件事一是wait用指数增长而不是固定间隔固定间隔在服务端故障恢复后会造成所有客户端同时涌入指数退避能把重连流量摊平二是max_retries必须写死没有上限的重连在 CI 里跑起来能把日志刷爆。另外重连时要重新走完整握手流程带鉴权头的场景还要确认 token 没有过期否则会出现连上了又被 1008 踢掉的鬼畜现象。4.3 鉴权与子协议从 401 到 1008 的排查路径WebSocket 的鉴权常见有两种模式握手阶段带Authorization头或 URL 里的 token以及握手完成后第一条消息携带凭证。前者的失败通常表现为握手直接失败工具要能展示 HTTP 状态码后者的失败往往表现为握手成功、随后服务端发 close 帧并带 1008。我在实际项目里的排查顺序一般是先把 URL 里的 token 和 Header 里的对应关系核对一遍然后打开抓包工具看握手请求头有没有被代理改写最后看服务端日志里有没有鉴权校验失败的具体原因。1008这个状态码本身只是一个“策略违规”的总称具体原因要靠服务端日志里的一句话来定位光看客户端这边猜是猜不出来的。子协议也是容易忽略的点对应握手里的Sec-WebSocket-Protocol头。如果服务端声明只支持某个协议名客户端的握手请求头里又没带协商就会失败。命令行工具一般用-s参数指定Python 脚本里则在create_connection的subprotocols参数传。测试时我两条都会跑一遍带和不带子协议确认服务端两种路径的行为都符合预期避免上线后才发现某一类客户端握手必失败。5. 避坑与排查五个翻车现场和对应的解决办法5.1 握手成功但收不到推送原因是分片没拼接现象日志里连接正常建立也能发出消息但服务端推送的业务消息永远少一块偶尔第一条能显示第二条开始就是残缺内容像是消息被截断。原因服务端出于效率把大消息切成多个数据帧发送客户端只处理了第一帧。对最终用户来说这相当于消息丢了但抓包一看每一帧都在只是客户端没按协议把分片接续起来。问题更多出现在自己写的简化客户端或某些轻量工具上成熟的库一般会自动重组分片。解决办法在客户端每帧回调里把FIN和opcode打出来如果发现FIN0连续出现基本可以断定是分片重组缺失def on_message(ws, message): print(fFIN{ws.frame.fin} opcode{ws.frame.opcode} payload_len{len(message)})接着把FIN0的负载先缓存到缓冲区等同一 opcode 下出现FIN1的帧再拼起来交给业务层。这个坑在本地小消息测试时根本看不到你以为工具没问题实际只是没触发大消息路径。5.2 wss 连不上本地测试环境先把证书校验关掉现象wss://127.0.0.1:8443一直握手超时或者报证书错误换成ws://立刻能连上本地测试服务本身是正常的。原因本地环境大多用自签证书而标准库和命令行工具默认会校验证书链自签证书不在受信列表里连接被客户端自己掐断。少数情况是证书里没有把127.0.0.1写进 SANIP 连接也会被判定为证书不匹配。解决办法命令行工具里加-n或--no-check跳过证书校验Python 脚本里给create_connection传sslopt参数import ssl import websocket ws websocket.create_connection( wss://127.0.0.1:8443/ws, sslopt{cert_reqs: ssl.CERT_NONE} )这个操作只允许在本地联调环境使用。测试环境如果也默认跳过证书校验回放留证的证据链会缺一环安全审计时很难解释。我的习惯是测试环境也先压一份正式证书实在没有才走这个后门但必须在配置文件里显式标注insecuretrue防止脚本被误带到生产环境。5.3 收到 1006 异常关闭服务端日志却是一切正常现象客户端跑一段时间后抛WebSocketConnectionClosedException关闭码是 1006翻服务端应用日志看不到任何异常。原因1006 不是服务端发的正常关闭码而是底层 TCP 连接被某层设备或代理静默掐断后客户端自己的推断。最常见的场景是反向代理的空闲超时把长时间没有数据传输的连接杀掉而应用日志不会记录这一层的事件所以看起来一切正常。解决办法先确认心跳是否真的在按预期发送很多“长连接”只是建立了连接脚本里忘了定时心跳。然后把抓包目标放在客户端所在网卡看断连瞬间是 FIN 还是 RST如果对端 IP 发来 FIN再顺着链路往上排查代理和四层负载均衡的keepalive_timeout、proxy_read_timeout配置。把心跳间隔调到代理超时的一半问题基本能绕过去。我做这类排查时会把客户端收到 EOF 的系统时间和服务端日志里的空闲超时日志对齐十次里有八次能对得上。5.4 并发一多就大量超时先查文件描述符和 backlog现象脚本 100 并发全过调到 500 开始大量超时服务端 CPU 占用不高看起来不像性能瓶颈。原因客户端宿主机的ulimit -n限制了单个进程可打开的文件描述符数量每个线程一条连接对应的 socket 也是描述符超过限制后 socket 创建失败或处于等待态。很多初学者一上来就怀疑服务端结果查了半天服务端没有任何压力问题出在客户端这边。解决办法先调大当前 shell 的软限制和硬限制ulimit -n 65535 sysctl -w net.core.somaxconn1024前者解决描述符不够后者调 TCP accept 队列。如果服务端 backlog 默认 128突然涌入几百个连接时部分 accept 排队超时现象和客户端瓶颈几乎一样所以两边都要查。排查时先ulimit -n和netstat -s看当前进程再用ss -ln看服务端监听队列的 Send-Q确认是哪一侧先达到上限。5.5 中文消息乱码先别骂编码器看字节现象服务端返回的中文在客户端显示成乱码或者 Python 里打印报UnicodeDecodeError但同一份消息用别的工具看又是正常的。原因三种常见情况。一是服务端发的不是 UTF-8比如按 GBK 或 Latin-1 编码二是客户端用了错误编码解码比如文本帧默认按 UTF-8 解码但服务端实际发送的是二进制协议字节流三是 JSON 字符串里的\uXXXX转义被二次处理显示层出了问题。解决办法脚本里收到消息后不要直接print先用repr看原始内容再按明确编码解码raw ws.recv() print(repr(raw)) if isinstance(raw, str): text raw.encode(utf-8, errorsreplace).decode(utf-8) else: text raw.decode(utf-8, errorsreplace)把服务端声明的编码写在配置里脚本收到文本帧后按声明解码。遇到二进制帧时千万不能拿str去接要用bytes接再按需处理。如果服务端坚持发非 UTF-8协议上已经算违规这种问题最终要回到服务端改不要试图在测试端掩盖过去。6. 把轮子收进工具箱用 CLI 封装让测试结果可留证可回放工具再好用如果只停留在“这次能测通”下次复现还是得从零敲命令。我的做法是把前面所有脚本收进一个命令行入口跑一次测试自动留下三样东西原始请求帧的十六进制日志、回包断言结果、一份可读的 JSON 报告。实现不复杂本质是把测试函数包在命令行参数后面import json, sys import websocket def run_case(url, payload, expectNone): ws websocket.create_connection(url, timeout10) ws.send(json.dumps(payload)) resp json.loads(ws.recv()) ok expect is None or resp expect return {url: url, payload: payload, response: resp, ok: ok} if __name__ __main__: url sys.argv[1] with open(sys.argv[2], r) as f: cases json.load(f) report [run_case(url, c[payload], c.get(expect)) for c in cases] with open(report.json, w) as f: json.dump(report, f, indent2, ensure_asciiFalse) exit(0 if all(r[ok] for r in report) else 1)每次跑完把report.json存档文件名带上时间戳。下次有人说服务端改了协议就重跑同一份用例文件diff 两份报告是回归还是环境差异一目了然。命令行返回码也很有用非 0 退出码可以直接接进 CI 流水线让长连接接口在每次发布后自动验一遍不需要人工盯。在这个基础上我还会在用例文件里固定一条最基础的心跳-断连-重连剧本作为每次接手新长连接服务的必跑项。从那以后我每次拿到一套新的 WebSocket 服务都强制先走一遍握手、心跳、断连重连、并发冒烟四步确认工具能看到帧和关闭码再开始业务测试。这个小习惯帮我挡下过好多次“客户端没问题”的误会希望帮到你。本文还有配套的精品资源点击获取