简介这是一份面向易语言开发者及前端初学者的 WebSocket 实时双向通信示例源码包聚焦于传统 HTTP 请求响应模式难以满足的即时数据交换需求可应用于聊天室、行情推送、在线状态同步等实时场景。压缩包共 3 个文件大小仅 10KB包含易语言源码、HTML5 页面和配套的样式表源码完全没有依赖任何第三方模块仅基于易语言支持库实现适合需要快速理解 WebSocket 底层交互逻辑的读者直接阅读和调试。目前已有 585 人学习下载。通过这个示例读者可以看到易语言端如何监听连接、接收并解析来自 WebSocket 客户端的数据以及如何将响应编码后发送回去同时也能对照 HTML5 页面中的 WebSocket 对象学习创建连接、发送与接收消息等关键接口的实际用法是入门实时网络编程和后续扩展 wss 安全连接的良好起点也可作为改造成更复杂实时应用的基础模板。1. 从一次Web实时联动说起易语言为什么要接WebSocket1.1 一个真实到不能再真实的需求场景前阵子朋友让我帮忙把一个用易语言写的设备数据采集程序跟一个网页端的监控页面打通。设备数据从串口读上来要实时显示在网页上网页上点了某个按钮也要立刻变成一条指令下发到设备。我第一反应是用HTTP轮询凑合把页面端的刷新间隔控制在1秒也算“视觉实时”了。可真跑起来才发现问题一堆1秒一次的轮询服务器每时每刻都在处理大量无意义请求设备数据如果突然暴增页面最多也要等1秒才能看到新数据放在工业监控这种场景里非常膈应。更难受的是页面下发指令后设备返回结果的时间完全不可控轮询根本不知道什么时候去问结果最合适。换成WebSocket之后整个逻辑顺了很多。一条TCP长连接保持住设备来一条数据服务器主动往页面推一条页面发一条指令也能在毫秒级收到确认回调。最关键的是这套机制是“事件驱动”的服务器有数据才推没有数据就安静待着比睁着眼睛反复问省太多资源。这个经历让我彻底意识到不是所有通信场景都适合“一问一答”只要需要服务端主动推数据WebSocket基本就是最合理的选择。易语言虽然老牌但它在Windows生态下的socket封装其实一直很稳这套组合的潜力被低估了。1.2 哪些项目最需要“易语言 WebSocket”这个组合结合我接触过的项目这个组合的典型场景可以分成三类你可以对号入座看看自己属于哪一种。本地程序与网页端联动易语言负责操作本地的文件、窗口、硬件或游戏网页端负责展示和控制。比如本地采集程序把数据实时推给浏览器图表或者网页按钮触发本地自动化操作。上位机数据推送易语言通过串口、Modbus、TCP等协议从下位机收数据解析之后推给远端或者本地的Web管理页面实现设备状态的远程可视化。这类场景对实时性要求极高延迟一高就没法用。与云服务/平台对接很多第三方平台开放的是WebSocket接口比如实时行情、消息推送、协同工具的消息流。易语言程序要订阅这些数据源就必须按WebSocket协议接入。这三个场景有两个共同特点一是都要求连接长期存在、数据持续流动二是绝大多数是个人开发者或小团队在搞没有太多人力去养一套复杂的基础设施。所以能有一份结构清晰、能看懂、能改的源码骨架比什么都实在。下面我直接把协议原理和可落地的实现骨架摊开讲清楚。2. 协议核心握手、帧格式以及那个坑人的掩码2.1 握手一次伪装成HTTP的升级WebSocket的连接建立过程表面上就是一个HTTP升级请求。客户端往服务器发一段文本请求头长这样GET /ws HTTP/1.1 Host: 192.168.1.100:8080 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ Sec-WebSocket-Version: 13服务器收到后如果愿意升级会返回101 Switching Protocols然后在响应头里带上Sec-WebSocket-Accept。这个Accept值不是随便生成的有一个固定算法把请求里的Sec-WebSocket-Key拼上一个全局固定的GUID字符串258EAFA5-E914-47DA-95CA-C5AB0DC85B11对拼出来的结果做SHA1哈希再Base64编码。这个GUID是RFC 6455定义死的全世界任何实现都得用同一个。这里有一个很容易被新手跳过的地方客户端收到服务器的Accept值后最好自己用同样的算法算一遍跟服务器返回的值做比对。如果不一致说明中间环节出了问题或者服务器实现不标准这时候不要继续发数据直接断开重来能省后面很多排查时间。2.2 数据帧从字节角度拆解一条消息连接升级成功后所有数据都封装成“帧”传输。每帧的开头两个字节是元信息结构如下第一个字节最高位是FIN表示这帧是不是整条消息的最后一帧低4位是操作码opcode。操作码里常用的有这几个0x1表示文本帧0x2表示二进制帧0x8是关闭帧0x9是Ping0xA是Pong。第二个字节最高位是MASK掩码标志低7位是负载长度。长度字段有个三级跳跃规则小于126后头直接就是数据等于126那第二、三字节后还要跟上2字节的真实长度等于127要跟上8字节的真实长度。写代码的时候最容易在这里出错。举个例子我要发送文本“ABC”三个字节那帧就是0x81 0x83 掩码密钥(4字节) 异或后的ABC。其中0x81的二进制是10000001FIN1opcode10x83的二进制是10000011MASK1负载长度3。2.3 掩码客户端独有的“必选项”掩码是WebSocket协议里最反直觉的设计。协议规定客户端发给服务器的帧MASK位必须为1而且数据区必须用4字节的随机密钥做XOR异或加密。服务器发给客户端的帧MASK位通常为0不需要异或。这种不对称让很多人一开始就懵。我记得有次调试抓包看到自己发出去的字节流跟服务器收进去的不一样折腾了半天才意识到客户端所有数据帧都必须做掩码。网上很多早期的易语言教程因为是从某个简化版C代码里抄来的经常把掩码这个环节丢掉结果连公共WebSocket服务就总被断开。你如果遇到“连接建立成功但一发送数据就被服务器掐断”十有八九就是掩码没做或者做错了。3. 方案选型DLL封装、成熟框架还是手写协议3.1 三条路线的真实差异在易语言里做WebSocket起手有三条路。我直接给一张对比表你看完心里就有数了方案开发成本可控性依赖情况适合场景第三方模块/DLL极低低需要附带额外文件快速验证、临时工具成熟框架/套件低中框架体积较大正式项目、长期维护基于socket手写协议高极高无学习、定制、深度排错社区里做配套库的团队不少比如以通讯为核心的HP-Socket套件、面向Web服务封装的E2EE套件都内置了WebSocket客户端和服务端实现。说实话用这些库开发效率非常高几行代码就能跑通一个连接特别适合“今天就要出Demo”的场景。但它们也有一个通病一旦出现问题你很难知道底层卡在哪一步。我见过有人在群里问“为什么连不上”把日志贴出来底层发生了什么全是黑盒。3.2 我为什么最终选择手写协议我在项目里是分两步走的先用现成模块快速验证服务器的地址、路由和消息格式是通的确认对方支持WebSocket协议然后回归到底层socket自己把握手、组帧、解帧、心跳全部实现一遍。这么做主要基于三点考虑。第一上手门槛真的不高。WebSocket协议文本不长核心就握手和帧两个部分总共不到一千行代码的体量在易语言里用纯socket命令完全可以落地。第二手写之后所有数据都在自己手里收发哪个环节出问题加个调试输出就能定位不用去猜库的行为。第三很多业务场景需要自定义心跳间隔、自定义关闭行为、自定义重连策略这些在框架里反而不方便调。如果你也想省事又把源码拿到手必须每一行都看懂我建议你也走“先用模块验证再手写协议”这条路。不冲突而且是很好的学习路径。4. 核心源码骨架握手、组帧、解帧、心跳一气呵成4.1 握手请求的构造与服务器校验用易语言手写WebSocket客户端第一步是建立TCP连接并发送HTTP升级请求。这里的架构我习惯分成四个部分握手、发送帧、接收帧、心跳管理。先用一个简单的字节集构建请求.版本 2 .支持库 spec .子程序 构建握手请求, 文本型 .参数 服务器地址, 文本型 .参数 请求路径, 文本型 .参数 密钥, 文本型 .局部变量 请求, 文本型 请求 “GET ” 请求路径 “ HTTP/1.1” #换行符 请求 请求 “Host: ” 服务器地址 #换行符 请求 请求 “Upgrade: websocket” #换行符 请求 请求 “Connection: Upgrade” #换行符 请求 请求 “Sec-WebSocket-Key: ” 密钥 #换行符 请求 请求 “Sec-WebSocket-Version: 13” #换行符 #换行符 返回 (请求)这里有两件事必须说明第一Sec-WebSocket-Key是16字节随机数据的Base64编码不要写死一个固定值否则服务器可能拒绝连接第二请求头必须以两个换行符结束代表头部结束这个细节漏了服务器会一直等你。收到服务器的响应后要从中提取Sec-WebSocket-Accept的值然后本地算一次.子程序 校验握手响应, 逻辑型 .参数 响应文本, 文本型 .参数 原始密钥, 文本型 .局部变量 期望值, 文本型 .局部变量 实际值, 文本型 期望值 取SHA1Base64 (原始密钥 “258EAFA5-E914-47DA-95CA-C5AB0DC85B11”) 实际值 取响应头字段 (响应文本, “Sec-WebSocket-Accept”) 返回 (期望值 实际值)取SHA1Base64这个函数在易语言里可以通过取数据摘要的方式拿到没有现成命令就自己写一个SHA1加Base64转换。校验通过才能把连接状态切到“已连接”。4.2 发送帧多字节长度和随机掩码的拼装发送文本消息的时候核心是组帧函数。我把它拆成两个子步骤先把文本转成UTF-8字节集再封装成帧。易语言默认文本是GBK编码转UTF-8这一步不能省否则收到的就会是乱码。.子程序 封装文本帧, 字节集, 公开 .参数 文本内容, 文本型 .局部变量 负载, 字节集 .局部变量 负载长度, 整数型 .局部变量 头部, 字节集 .局部变量 掩码, 字节集 .局部变量 完成帧, 字节集 负载 文本转UTF8 (文本内容) 负载长度 取字节集长度 (负载) 掩码 生成随机4字节 () 构造帧头 如果 (负载长度 ≤ 125) 头部 { 129, 128 负载长度 } 否则如果 (负载长度 ≤ 65535) 头部 { 129, 254, 负载长度 8, 负载长度 255 } 否则 头部 { 129, 255, 0, 0, 0, 0, 0, 0, 0, 负载长度 } 如果结束 完成帧 头部 掩码 负载按掩码异或 (负载, 掩码) 返回 (完成帧)注意第一字节我写的是129十进制十六进制就是0x81代表FIN1且opcode1的文本帧。第二字节的128就是0x80把MASK位置1。254是0xFE即0x80 | 126表示后面跟2字节长度。长度字段的处理我是拆成了高8位和低8位两个字节不要用整数型直接拼接否则长度一超过127就会因为符号位变成负数整个包头都是错的。4.3 接收帧粘包、拆包和消息重组接收侧是整个实现里最容易出问题的部分。TCP是流式协议不保证消息边界所以你必须有一个缓冲区来承接所有收到的数据然后在缓冲区里不断解析把完整的帧挑出来处理剩余字节留在缓冲里等下一批数据。.子程序 接收数据处理, 整数型 .参数 新数据, 字节集 .局部变量 当前偏移, 整数型 .局部变量 数据长度, 整数型 .局部变量 第二字节, 整数型 .局部变量 掩码, 整数型 .局部变量 负载长度, 整数型 数据长度 取字节集长度 (新数据) 如果 (数据长度 2) 返回 (0) 头都凑不齐继续等 如果结束 第二字节 取字节 (新数据, 2) 负载长度 第二字节 且 127 如果 (负载长度 126) 需要再读2字节长度缓冲区不足则返回等待 负载长度 取字节 (新数据, 3) * 256 取字节 (新数据, 4) 当前偏移 4 否则如果 (负载长度 127) 这里处理8字节长度具体逻辑略 否则 当前偏移 2 如果结束 如果 (第二字节 且 128) ≠ 0 掩码 4 服务器发来的帧大多没有MASK但你的代码要兼容 如果结束 提取负载按操作码分发 如果 (取字节 (新数据, 1) 且 15 1) 消息文本 UTF8转文本 (负载) 触发消息回调 (消息文本) 如果结束这个解析函数每次必须保证“缓冲区够读一个完整帧的前两个字节”不够就先返回等更多数据到来。如果帧头里告诉你要读长度字段但缓冲区还不够也要一并等。这种处理思路跟串口接收粘包一模一样做过Modbus RTU的上位机开发很容易理解。4.4 心跳和优雅关闭别让连接死得不明不白WebSocket长连接空闲久了中间的路由器、防火墙可能会悄悄超时把连接掐掉而两端都不知情。解决方式就是心跳。我的做法是连接建立后启动一个定时器每10到30秒检查一次。如果上次收到任何一帧数据的时间已经超过阈值就主动发一个Ping帧然后等待Pong如果连续几次Ping都没等到Pong就判定连接已死走重连流程。Ping帧的组帧跟文本帧类似只是第一个字节变成0x89FIN1opcode9负载可以为空。服务器收到Ping后会回一个Pong帧第一个字节是0x8A。关闭连接也一样有讲究。客户端要关闭时应该先发一个关闭帧opcode8带一个可选的状态码比如1000表示正常关闭然后等服务器也回一个关闭帧再断开底层TCP。这个流程叫“优雅关闭”能保证服务器端状态正常下次重连不会被判成异常。很多人图省事直接关socket服务器那边会记录一次异常断开有些服务端逻辑里会因此临时拉黑这个客户端IP。5. 踩坑实录五个让我熬夜的断线和乱码问题5.1 “stream disconnected before completion”的排查路径这个报错我在调试时碰到过好几次。字面意思是“在消息完成之前数据流断开了”常见原因有三个一是握手成功后还没真正切换到WebSocket模式就急着发数据二是接收端的解析逻辑读了错误长度导致数据包不完整服务器认为协议违规直接断开三是对方主动关闭了连接而客户端没有正确处理关闭帧。我的排查顺序是先在发送握手请求后等一下确认收到101 Switching Protocols和正确的Accept值再开始发数据帧然后在接收解析入口加日志把第一字节、第二字节、长度字段全部打印出来对一遍最后用网络抓包看最后一个数据包确认是服务器断的还是本机断的。按这个顺序查基本半小时能定位。5.2 消息“只收到一半”和“塞进来两条”这个问题本质是帧边界没处理好。如果你每次socket收到数据就直接当成一整条消息去解析那肯定会在数据量大的时候随机出错。比如服务器一次推了两条消息你的解析函数只取第一条尾部的一部分第二条就丢了反过来一条消息被拆成好几段TCP你只读第一段消息就永远不完整。解决办法就是我上面写的缓冲区加循环解析。所有接收数据先进缓冲区每次循环尽量多解析出完整帧解析到第几帧就处理几帧剩下的留在缓冲区里。这个缓冲区要设计成“动态追加”的不是每次覆盖否则还是会丢。5.3 中文内容全部乱码编码转换的锅易语言里的文本型数据默认是ANSI编码在中文Windows下就是GBK。而WebSocket文本帧的标准编码是UTF-8这俩不转换收发中文肯定乱。具体说发送前要把易语言的文本转成UTF-8字节集再封帧接收后要把负载字节集从UTF-8解码回GBK文本。这个转换要做在封帧和解帧函数内部而不是在业务逻辑里到处转。我之前有个项目业务层那里转一次网络层这里又转一次结果文件保存是好的发到服务器又乱了查了半天才发现是双重转换。5.4 连接“假死”心跳和超时管理有一种诡异的断线是“看着连着实际已经死了”。原因是TCP连接一方崩溃或网络中断后只要双方都没有数据收发另一端很难立刻发现。服务器可能在某个时间点悄悄断开了连接但客户端本地没有任何感知界面还一直显示“已连接”数据早就推不进来了。这类问题只能靠心跳解。心跳的意义不只是“保活”更是“检测”。定时Ping等Pong等不到就主动断开给上层发一个“连接断开”事件再走重连逻辑。没有心跳的WebSocket客户端跑一两天后连接掉光是必然的不是运气问题。5.5 服务器重启后客户端全部掉线的应对服务器一重启所有WebSocket连接瞬间全断。如果客户端没有重连机制就只能等人手动重启程序如果有重连机制但策略不对比如所有客户端都固定3秒重试一次服务器一恢复一瞬间几千个连接挤上来很容易把刚启动的服务器再次压垮。正确的做法是加退避机制第一次重连等1秒第二次等2秒第三次等4秒每次翻倍封顶比如30秒并且每次加一个随机抖动值。这样服务器恢复后客户端是像波浪一样分批涌上来的而不是一堵墙横着拍过去。6. 一套可复用的通讯框架组织方式6.1 分层结构与职责边界如果你不满足于“能跑”想把这套通讯能力沉淀成可复用的代码我强烈建议你按三层组织协议层只负责握手、组帧、解帧、掩码、心跳帧的构造和解析。不掺任何业务字段不关心你发的是设备数据还是游戏数据。连接管理层负责TCP连接生命周期、心跳定时器、断线重连、状态通知。向上层只暴露三个事件已连接、已断开、收到消息。业务层把协议层解出来的数据映射成业务对象把业务操作转成协议层的发送调用。跟WebSocket细节完全解耦以后换协议、换服务器都不影响业务代码。这个分层的好处是协议层和连接管理层可以单独测试出问题不用连带着业务逻辑一起翻。我在项目里就是这么拆的后来要从WebSocket换成TCP私有协议只换了协议层连接管理和业务层一行没动。6.2 连接状态机与断线重连连接管理我习惯用显式状态机而不是一堆布尔型标志位。核心状态就五个未连接、正在连接、已连接、正在断开、已断开。每次状态切换都记一条带时间戳和原因的日志出问题时打开日志一看就知道连到哪一步卡住了。当前状态触发事件下一状态典型动作未连接用户发起连接正在连接创建socket发送握手正在连接收到正确的握手响应已连接启动心跳定时器正在连接握手超时/校验失败已断开释放socket安排重连已连接收到任何数据帧已连接重置空闲计时器已连接心跳Ping多次无回包已断开主动关闭底层连接已断开重连计时器到点正在连接重新创建socket重连的时候还有一个细节容易被忽略要区分“可以重连”和“不该重连”。如果是心跳超时或者网络闪断直接重连没问题但如果服务器明确返回了一个带错误状态码的关闭帧比如4013表示认证失败那就绝对不能继续重连否则客户端会变成一台“重连永动机”把服务器日志和网络带宽全浪费掉。这种情况应该停下来把错误上报给用户。6.3 我现在的习惯做法最后分享一个我在项目里的习惯代码里所有关键路径都留调试输出但打印级别要分好平时只输出状态切换和异常不进每一帧的十六进制。等真正出问题的时候再打开帧级调试开关把收发字节流完整记下来。这样既能日常使用又能在排查疑难问题时拿到第一手数据不用临时改代码。这套东西做完之后再遇到什么“网页控制易语言程序”“易语言订阅实时数据”“上位机推数据给浏览器”之类的需求基本就是换一下业务层的事不用再从头趟坑了。本文还有配套的精品资源点击获取