简介微信小程序 TCP/IP 长连接示例源码适合需要在微信小程序端实现稳定网络长连接的小程序开发者也适合作为学习 TCP/IP 协议在移动端落地的参考案例。压缩包内共 35 个文件以 Go 服务端源码为主18 个 .go 文件搭配小程序前端 js/wxml/wxss、配置文件 json 及说明文档包体约 39KB。服务端与小程序客户端均已覆盖可直接对照研究长连接的建立、心跳保持等关键逻辑。整套代码目录结构简洁既能帮助开发者理解小程序 socket 接口的调用方式也能为自建 TCP/IP 长连接服务提供可复用的服务端骨架。目前已吸引 2017 人浏览学习适合具备一定小程序基础、希望深入网络通信细节的读者参考。1. 微信小程序 TCP/IP 长连接源码先跑通服务端再谈小程序端微信小程序要做 TCP/IP 长连接很多团队的默认方案是 WebSocket但真正对接过自研协议设备、工业网关、私有化服务器的开发者迟早会遇到必须裸 TCP 的场景。这份《微信小程序 TCP,IP长连接源码》把服务端、HTML 联调页、小程序端三件事装在同一个压缩包里README、LICENSE 齐全服务端代码在 fans-server-master 目录下。它解决的问题很具体小程序怎么通过wx.createTCPSocket建立底层网络协议的 TCP 长连接怎么保活怎么从浏览器端先验证服务端是不是好的。适合要做 IoT 小程序、设备控制面板、内部长连接工具的从业者新手和老手都能找到自己需要的那一层。2. 小程序里的 TCP 长连接先搞清 API 和心跳再动手2.1 TCPSocket 是小程序网络协议里的原生入口微信小程序默认只有wx.request和wx.connectSocket这两个网络接口前者走 HTTP 短连接后者走 WebSocket。很多人不知道的是基础库在较新版本里开放了wx.createTCPSocket这才让小程序可以直接走 TCP/IP 长连接不必把业务协议强行塞进 WebSocket 帧里。TCPSocket 的行为和 Node.js 里的 net.Socket 很像连接、收消息、断线、报错都有独立回调数据以 ArrayBuffer 为最小单位读写。需要说明的是这个 API 是实验性能力真机上对基础库版本有硬性要求开发工具里也要做相应配置。这段代码是整个链路的第一道门// wx/pages/conn/conn.js 中建立 TCP 连接的骨架 const tcp wx.createTCPSocket() tcp.connect({ address: 192.168.1.100, // 服务端 IP局域网真机调试时用电脑 IP port: 4000 // 服务端端口要和 fans-server 保持一致 }) tcp.onConnect(() { console.log(TCP 已连接) }) tcp.onMessage(res { // res.message 是 ArrayBuffer需要按协议自己解析 console.log(收到数据, res.message) }) tcp.onError(err { console.error(TCP 错误, err) })wx.createTCPSocket()会返回一个 TCPSocket 实例所有事件都挂在实例上。连接参数只有两个address 和 port没有 path、没有额外 header跟 HTTP 完全不同。需要注意onConnect才是可控的起点要在回调里再发业务数据。很多人第一次写的时候把tcp.write()直接放在connect()后面十次里有八次包发不出去因为 TCP 握手还没完成数据已经丢了。2.2 三次握手只是开始保活靠的是应用层心跳TCP/IP 长连接里最容易误解的事就是把三次握手当成连接可靠的证据。三次握手成功只代表两端网络可达不代表连接永远活着。移动端网络环境极其复杂Wi-Fi 切 4G、电梯里信号抖动、路由器 NAT 超时都会让连接静默死掉。TCP 协议栈本身有 keepalive 机制但系统默认探测周期是 2 小时在小程序这种场景里完全不够用。所以长连接必须做应用层心跳。常见做法是小程序端每隔 30 秒发一个心跳包服务端在 90 秒内没收到任何数据就断开这条连接。心跳包可以复用业务数据通路也可以单独定义一种指令类型。这个源码包里的服务端和客户端都是围绕这条心跳链路设计的后文会分别展开。三个关键时间参数可以先记住参数常见取值说明心跳间隔30s客户端定时发送心跳包的周期服务端超时90s超过该时间无数据则主动断开通常是心跳间隔的 3 倍重连退避1s、2s、4s、8s…封顶 60s断开后按指数退避重连避免风暴如果服务端超时设得和心跳间隔一样近网络一抖动就误杀连接设得太远又会让死连接挂很久。我一般会把超时控制在心跳间隔的 3 倍左右给重传留出缓冲。2.3 WebSocket 与裸 TCP 的边界在哪选型阶段绕不开一个问题到底用 WebSocket 还是裸 TCP我的判断标准很简单如果通信双方都在你控制范围内而且业务需要二进制流、半包粘包处理、私有协议头那就上 TCP如果只是为了前后端推送、且服务端是公网 HTTP 服务WebSocket 省事得多。WebSocket 本身的帧格式是固定的协议头开销大而且不是所有 IoT 网关都实现了 WebSocket 服务端。这个项目走的是 TCP 路径属私有大客户端逻辑的典型场景。服务端在 fans-server-master 里实现了一套简单的 TCP 监听和超时回收逻辑小程序端负责连接和心跳HTML 端负责在浏览器里先验证服务端存活状态。三层一起看才能把链路问题定位准确。3. 运行服务端 fans-server先把网络协议这层地基打牢3.1 解压与目录结构拿到压缩包后先解压再逐层看不要急着往开发者工具里拖。目录结构大致是这样的fans-server-master 是服务端工程html 是浏览器联调页client 是命令行或脚本测试客户端wx 才是微信小程序工程。README.md 里一般会写明启动顺序和端口约定LICENSE 说明使用边界。# 解压并查看顶层结构 unzip 微信小程序TCP长连接源码.rar -d tcp-demo cd tcp-demo ls -la # 预期会看到 fans-server-master、client、html、wx 这几个目录这里有个习惯问题很多人解压后直接打开 wx 目录发现连不上服务器回头才意识到服务端压根没启动。TCP 长连接是两端的事任何一端缺席另一端只能看到报错。所以拆这个包一定要按照「服务端 → 联调页 → 小程序端」的顺序来。3.2 启动 TCP 服务端并确认监听端口进入 fans-server-master 后先看 README 和 package.json 里的 scripts 段。这套服务端从文件布局看是 Node.js 系的 socket 服务常见做法是安装依赖后直接启动监听脚本cd fans-server-master npm install # 启动脚本以 README 为准常见是 npm start 或 node server.js npm start启动成功的标志不是终端不再报错而是能看到类似server listening on 0.0.0.0:4000的日志。如果终端没有任何输出大概率监听逻辑写在了某个需要手动触发的函数里去 README 里找启动命令的完整形态。端口号要记录下来后面 HTML 联调页和小程序端都要填同一个端口。服务端这段代码虽然不用改但建议扫一眼超时控制逻辑。典型的实现是在每个 socket 上设置setTimeout收到任意数据就重置计时器超时直接socket.end()// fans-server-master/server 中常见的心跳超时逻辑 const HEARTBEAT_TIMEOUT 90 * 1000 // 90 秒没数据就断开 server.on(connection, socket { socket.setTimeout(HEARTBEAT_TIMEOUT) socket.on(timeout, () { // 长时间没有心跳包判定为死连接 socket.end() }) socket.on(data, () { // 收到任何数据都视为活跃重置计时器 socket.setTimeout(HEARTBEAT_TIMEOUT) }) })这段逻辑的关键在socket.setTimeout的语义它不是指 TCP 协议栈的 keepalive而是应用层空闲超时。每收到一次数据就重新计时这样客户端只要心跳不断连接就不会被服务端误杀。参数HEARTBEAT_TIMEOUT可以随业务调整但记住一个原则——服务端超时必须是客户端心跳间隔的 3 倍左右。设成 5 倍也行但死连接存活的周期会更长资源回收更慢。3.3 用 HTML 联调页验证服务端浏览器里没法直接发起裸 TCP 连接所以 html 目录里的联调页通常走 WebSocket 或 HTTP 桥接把服务端的在线状态和收发能力先验证一遍。这一步的目标是证明「服务端本身是好的」排除掉服务端问题后再去调小程序端。在浏览器里打开 html 页面填上服务端 IP 和端口发起连接。如果页面能显示connected并收到服务端下发的数据说明服务端监听正常、端口没被防火墙拦。这里要注意联调页的桥接方式不一定和 TCP 直连完全等价它能验证的是服务端进程活着、端口可访问、收发链路通着但 websocket 有自己的心跳机制不能完全模拟小程序 TCP 的断线行为。所以它只能当辅助手段最终还是要回小程序看真实表现。联通之后顺手确认防火墙状态# 查看端口 4000 是否在监听 netstat -tunlp | grep 4000如果服务端监听在 127.0.0.1 上而小程序要连的是局域网或公网 IP那谁也连不上。这类问题后面避坑章节会展开。总之服务端这层先跑通后面的调试成本能省一半。4. 把 wx 目录放进开发者工具连接、心跳与重连落地4.1 导入工程前的两个配置微信开发者工具导入 wx 目录后第一件事不是写代码是关掉域名校验。小程序默认的安全策略会拦截一切非白名单网络请求本地联调时必须在开发者工具的「详情 → 本地设置」里勾选「不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书」。这是本地开发 TCP 长连接绕不开的一步否则wx.createTCPSocket可能直接被本地环境拦掉。第二个配置是基础库版本。TCPSocket 需要较新的基础库在开发者工具右上角「详情 → 本地设置 → 调试基础库」里选一个较新版本。如果版本太老调用wx.createTCPSocket()会直接报not a function。4.2 小程序端连接代码的完整形态wx 目录下的小程序端代码核心逻辑集中在连接管理这一块。以下是我按项目中常见结构还原的完整连接流程包含连接、监听、心跳和重连四段逻辑// wx/utils/tcp-client.js —— 小程序 TCP 长连接管理 const HEARTBEAT_INTERVAL 30000 // 心跳间隔 30 秒 const RECONNECT_BASE_DELAY 1000 // 重连基数 1 秒 const MAX_RECONNECT_DELAY 60000 // 重连封顶 60 秒 let tcpSocket null let heartbeatTimer null let reconnectCount 0 let reconnectTimer null function connect(options) { if (tcpSocket) { tcpSocket.close() } tcpSocket wx.createTCPSocket() tcpSocket.onConnect(() { console.log(TCP 已连接) reconnectCount 0 // 连接成功重置重连计数 startHeartbeat() }) tcpSocket.onMessage(res { // 收到的数据在 res.message 里类型是 ArrayBuffer const bytes new Uint8Array(res.message) handleBusinessData(bytes) }) tcpSocket.onError(err { console.error(TCP 错误, err) stopHeartbeat() scheduleReconnect() }) tcpSocket.onClose(() { console.warn(TCP 连接被关闭) stopHeartbeat() scheduleReconnect() }) tcpSocket.connect({ address: options.address, port: options.port }) } function startHeartbeat() { stopHeartbeat() heartbeatTimer setInterval(() { const heartbeatPackage buildHeartbeatPackage() tcpSocket.write(heartbeatPackage) }, HEARTBEAT_INTERVAL) } function stopHeartbeat() { if (heartbeatTimer) { clearInterval(heartbeatTimer) heartbeatTimer null } } function scheduleReconnect() { if (reconnectTimer) { return } // 指数退避1s、2s、4s、8s封顶 60s const delay Math.min( RECONNECT_BASE_DELAY * Math.pow(2, reconnectCount), MAX_RECONNECT_DELAY ) reconnectCount 1 reconnectTimer setTimeout(() { reconnectTimer null connect({ address: options.address, port: options.port }) }, delay) } module.exports { connect, close: closeConnection }这段代码里有三个地方必须看注释onConnect里重置reconnectCount是防止频繁抖动后重连计数无限增长onClose和onError都要触发scheduleReconnect少一个就会出现在某类异常下永远不重连的情况scheduleReconnect里的reconnectTimer判空是为了避免同时触发多个重连定时器造成风暴。4.3 心跳包的构造与协议对齐心跳包长什么样取决于服务端怎么解析。常见做法是定义一个固定长度的结构体包含帧头、命令字、序列号三部分。下面的代码演示了怎么用 DataView 拼一个 8 字节的心跳包function buildHeartbeatPackage() { const buffer new ArrayBuffer(8) const view new DataView(buffer) view.setUint8(0, 0xAA) // 帧头固定 0xAA用于暴乱数据识别 view.setUint8(1, 0x01) // 命令字0x01 代表心跳 view.setUint16(2, seq, false) // 序列号大端序 view.setUint32(4, 0, false) // 预留字段补零 return buffer }注意setUint16和setUint32的第三个参数传了false代表大端序。TCP 协议里多字节字段的字节序必须和服务器一致如果服务端是 Java 或 C 写的默认就是大端序如果服务端用 Node.js 的 Buffer 读写一般也是大端序。字节序不对会出现「连接正常、数据乱码」的诡异现象而且极难排查。4.4 参数对齐表联调时把下面这张表打印出来贴屏幕边上每一项都要在两端确认过缺一个就可能导致连接在特定场景下异常参数项小程序端服务端备注服务端 IPwx 目录 config 文件监听 0.0.0.0真机调试务必填局域网或公网可达 IP端口与 server 一致启动监听端口两端必须严格一致心跳间隔30s 定时器无感知服务端只认数据活跃空闲超时不涉及90s必须大于等于心跳间隔 3 倍帧格式帧头 命令字 序列号按相同格式解码字节序要统一5. 避坑微信小程序 TCP/IP 长连接的五个常见问题5.1 开发者工具报「not a function」现象在 wx 目录里调用wx.createTCPSocket()控制台直接报wx.createTCPSocket is not a function。原因基础库版本太老。TCPSocket API 不是从一开始就有的旧基础库里根本不存在这个方法。解决在开发者工具「详情 → 本地设置」里把调试基础库切换到较新版本同时在 app.json 里确认没有手动 lock 基础库版本。真机上如果有用户停留在旧版本客户端代码里要做能力判断if (!wx.createTCPSocket) { wx.showModal({ title: 提示, content: 当前微信版本过低不支持 TCP 长连接 }) return }5.2 开发者工具能连真机一碰就断现象工具里连接服务端一切正常换成真机调试立刻失败或者连上几秒后掉线。原因真机环境比工具复杂得多。iOS 会弹本地网络权限Android 部分机型对后台网络连接有省电策略再加上真机连的 Wi-Fi 可能和服务端不在同一网段。解决先确认手机和服务端在同一个局域网然后 iOS 到「设置 → 隐私 → 本地网络」里打开小程序的本地网络权限。Android 端要把小程序的电池优化设为不限制不然息屏后 TCP 连接会被系统杀掉心跳自然也就断了。这类问题表面看是网络问题本质是移动端省电策略在作祟。5.3 连接断开后永远不再重连现象程序启动后第一次连接成功了一旦断线界面上就再也没恢复过。看日志发现onError和onClose触发了但没有后续动作。原因只监听了onError没监听onClose或者重连逻辑写在了某个只执行一次的初始化函数里。TCP 断开时可能会走onError也可能直接走onClose这两者不是互斥的只处理其中一个是挡不住所有场景的。解决把重连入口统一收口到一个函数里onError和onClose都调它。比较稳妥的写法是在onClose里也调用和onError完全相同的处理函数通过reconnectTimer判空来防止重复触发。我一般会同时在这里记录重连次数超过 5 次后弹出提示或切换到备用服务器地址。5.4 服务端收到了连接却收不到业务数据现象服务端日志里能看到新的 socket 连接进来但业务数据迟迟不来或者发出去的全是乱码。原因多半不是网络问题是应用层协议问题。小程序端在connect调用后立刻write数据在 TCP 握手完成前就发出去了或者多字节字段字节序不对服务端按大端读、小程序按小端写解出来的数据全是歪的。解决所有业务数据一律在onConnect回调里发不要在外层直接write。字节序统一走大端序写的时候setUint16、setUint32的第三个参数显式传false不要依赖默认值。如果服务端解出来的数据是0x01 0x02反过来的优先检查字节序而不是检查网络。5.5 长连接挂了一晚上早上发现状态是「假活」现象界面显示连接正常但服务端那头其实早就把连接断开了。敲门是心跳定时器还在跑看起来连接还在。原因TCP 断开如果没触发onError或onClose小程序端会进入「假活」状态。典型场景是手机长时间息屏系统冻结了应用进程心跳定时器也停了等服务端超时断开后进程恢复时并没有立刻感知到断线。解决除了心跳包之外再做一层「断线检测」连续多次心跳没收到服务端的确认响应就主动close()并触发重连。还有一个实用技巧监听wx.onNetworkStatusChange网络状态从无网切回有网时强制重连一次避免网络切换后活在一个已经失效的连接上。6. 验证长连接是否真的活着两个可观测的技巧长连接项目最怕的就是黑匣子连接好像活着但业务数据推不下来。我从几个类似项目里总结出来的思路是把连接状态变成可见、可统计、可回溯的数据而不是靠肉眼看界面。第一个技巧是服务端日志打时间戳。每收到一个心跳包就输出一次当前时间比对相邻两条日志的间隔是否稳定在 30 秒左右。如果间隔突然变成 90 秒甚至更长说明客户端的心跳定时器被系统冻结过这条链路的可靠性就要重新评估。用命令验证也很直接netstat -tn | grep 4000 # ESTABLISHED 状态说明 TCP 层连接还在需要注意的是ESTABLISHED只代表 TCP 连接没有被内核回收不代表应用层是健康的真正的状态要以心跳数据为准。第二个技巧是在小程序界面放一个连接状态指示器。用一个计数器变量记录收包次数每收到一包就加一界面上的数字跟着涨。这样不用看控制台用户一眼就知道连接是不是活的。这个方案在我接过的项目里帮了不少忙尤其是给客户做演示的时候一张截图比你解释半小时都有说服力。顺带说一个让我印象深刻的翻车经历有次上线前测试服务端日志显示连接稳定小程序界面也显示正常结果压测时发现同一时刻有几十个死连接挂在服务器上。查到最后是重连逻辑没做退避每次断线所有客户端同时重连造成了连接风暴。从那以后我每次写完长连接代码都会强制走一遍「杀进程 → 断网 → 恢复网络」的完整流程盯着日志确认重连间隔符合预期确认没有并发风暴才敢上线。这套验证流程也建议你试一遍希望帮到你。本文还有配套的精品资源点击获取