简介这是一份面向微信小程序开发者与网络协议学习者的实战型源码资源聚焦TCP/IP长连接通信在小程序端的实现方案适用于即时消息、实时数据推送等需要双向持久通信的业务场景。资源包含35个文件主体为18个Go语言编写的后端服务代码含server与client模块、7个前端JavaScript逻辑文件、3个WXSS样式文件及2个WXML页面结构文件辅以JSON配置、README说明与LICENSE协议整体压缩包仅39KB轻量易部署。已有397人下载学习适合具备基础小程序开发能力、希望深入理解WebSocket替代方案或自建轻量级长连接服务的中阶开发者。读者可直接复用服务端Go代码搭建TCP服务器结合小程序端JS完成连接管理、心跳保活与消息收发全流程配套截图与目录结构如fans-server-master清晰呈现项目分层设计便于快速上手与二次开发。1. 微信小程序源码含截图TCP,IP长连接不是“连上就行”而是“连得稳、断得明、重连快、不耗电”你拿到一份标着“微信小程序源码含截图TCP,IP长连接”的压缩包解压后看到app.js里有wx.connectSocket、onSocketOpen、onSocketMessage甚至还有reconnectTimer和pingInterval—— 但真跑起来用户反馈“进页面30秒就掉线”“切后台再回来白屏”“安卓机频繁重连失败”开发者工具 Network 面板里 WebSocket 连接状态飘忽不定抓包发现大量FIN和RST包。这不是代码没写而是对「微信小程序环境下的 TCP/IP 长连接」存在根本性误判小程序没有原生 TCP Socket API所谓“TCP,IP长连接”实际是基于 WebSocket 协议封装的、运行在微信安全沙箱中的、受平台强管控的持久化通信通道。它不等于net.Socket不走系统socket()系统调用无法自定义 IP 层参数更不能绕过微信的 TLS 强制加密和域名白名单。这份源码的价值不在于教你“怎么写 TCP”而在于展示如何在微信生态的硬约束下用有限的wx.connectSocket接口构建出具备心跳保活、异常感知、优雅降级、离线缓存能力的可靠通信链路。适合正在开发实时聊天、IoT 设备控制、股票行情推送、在线协作文档等强实时场景的小程序团队尤其适合已踩过“以为能用原生 TCP”“忽略小程序生命周期”“未处理 TLS 握手失败”三类典型翻车坑的中高级前端工程师。2. 为什么必须用 WebSocket 而非“真 TCP”微信小程序的网络能力边界与协议栈真相微信小程序的网络模型本质是「HTTP/HTTPS WebSocket」双轨制这是由微信客户端底层架构决定的。很多开发者拿到“TCP,IP长连接”标题就本能想用 Node.js 的net模块思维去套结果在app.js里写const socket new net.Socket()直接报错——因为小程序运行在 WebView 或 WKWebView 容器中JS 运行时完全隔离于系统网络栈所有网络请求必须经由微信客户端提供的wx.request、wx.uploadFile、wx.connectSocket等统一网关。这并非技术限制而是安全沙箱的刚性要求禁止直接访问 IP 地址、端口、原始 TCP 数据包强制走 HTTPS/WSS 加密通道所有域名需提前配置在request合法域名和socket合法域名白名单中。2.1 微信小程序网络能力矩阵哪些能做哪些绝对不行提示以下能力判断基于微信基础库 2.25.0当前主流版本旧版基础库如 1.x能力更弱务必检查wx.getSystemInfoSync().SDKVersion。能力项是否支持关键说明直接创建 TCP Socketnet.Socket/new WebSocket(tcp://...)❌ 绝对不支持小程序 JS 运行时无net模块WebSocket构造函数仅接受wss://或ws://协议且ws://在正式版中被禁用使用wx.connectSocket({ url: wss://api.example.com/ws })✅ 完全支持唯一官方支持的“长连接”方式底层由微信客户端实现 WebSocket 协议栈自动处理 TLS 握手、帧解析、心跳自定义 TCP/IP 层参数如 MSS、窗口大小、Nagle 算法开关❌ 不可访问参数由微信客户端内核控制JS 层无任何 API 暴露wx.connectSocket无相关配置项解析域名获取 IP 地址dns.lookup❌ 不支持小程序无 DNS 解析 API所有域名解析由微信客户端内部完成开发者不可见、不可控使用telnet ip 端口命令测试连通性❌ 无法执行小程序无命令行环境telnet是系统工具JS 层无法调用连通性验证只能通过wx.connectSocket的fail回调或服务端日志发送原始 IP 包如 ICMP ping、UDP 广播❌ 不支持所有网络通信必须走 HTTP(S) 或 WebSocket 协议无原始套接字权限这个矩阵决定了所谓“TCP,IP长连接”源码其核心必然是围绕wx.connectSocket的封装而非底层协议实现。它的价值在于把微信强制提供的 WebSocket 通道用工程化手段补足了缺失的能力——比如微信不提供“连接超时时间设置”源码就得自己加计时器微信不暴露TCP 三次握手状态源码就得靠onSocketOpen和fail回调组合推断微信不保证onSocketClose一定触发如进程被杀源码就得结合onHide/onShow生命周期做兜底。2.2 从 TCP 到 WebSocket一次必须理解的协议跃迁很多开发者纠结“为什么不能用 TCP”本质是对协议分层理解不深。我们来拆解一次真实通信你期望的 TCP 流程小程序 JS → 调用 net.Socket() → 系统 socket() → TCP 三次握手 → 发送 raw bytes → 接收 raw bytes这条路径在小程序里根本不存在。微信强制的 WebSocket 流程小程序 JS → wx.connectSocket({ url: wss://... }) → 微信客户端发起 HTTPS 握手 → 升级为 WebSocket 协议HTTP Upgrade→ 微信客户端管理 TCP 连接 → JS 层接收 onSocketOpen/onSocketMessage关键点在于WebSocket 是应用层协议运行在 TCP 之上而微信只开放了 WebSocket 这一层的 JS 接口TCP 层完全黑盒。这意味着你无法控制SYN包重传次数微信客户端内核决定你无法修改TCP MSS微信客户端根据网络类型自动协商你无法绕过 TLSwss://强制加密ws://仅调试可用你看到的onSocketError可能是 TLS 握手失败、DNS 解析超时、TCP 连接被中间设备重置RST、或 WebSocket 协议帧错误——但微信不告诉你具体是哪一层出的问题。所以源码里的“TCP,IP长连接”实则是用 WebSocket 协议模拟 TCP 长连接语义通过定时ping/pong帧维持连接活跃用消息序列号ACK 机制模拟可靠传输用本地队列重发策略补偿网络抖动。这不是“退而求其次”而是唯一合规路径。2.3 源码结构解剖一个典型“长连接”封装的核心模块拿到源码包先别急着跑打开目录看结构。一个经过实战检验的长连接封装通常包含以下 4 个核心文件命名可能略有差异但职责不变├── utils/ │ └── socketManager.js # 主管理器连接状态机、重连逻辑、消息分发 ├── services/ │ └── socketService.js # 业务接口login()、sendMsg()、subscribe() 等 ├── constants/ │ └── socketConst.js # 常量重连间隔、心跳周期、最大重试次数、错误码映射 └── app.js # 全局初始化在 onLaunch 中启动 socketManager其中socketManager.js是心脏。它不直接调用wx.connectSocket而是封装成一个状态机// utils/socketManager.js class SocketManager { constructor(options) { this.status CLOSED; // CLOSED, CONNECTING, OPEN, CLOSING this.reconnectCount 0; this.maxReconnect 5; this.pingInterval null; this.socketTask null; this.messageQueue []; // 未确认发送的消息队列 } connect() { if (this.status OPEN) return; if (this.status CONNECTING) return; // 防止重复 connect this.status CONNECTING; this.socketTask wx.connectSocket({ url: wss://api.example.com/ws, header: { X-Auth-Token: wx.getStorageSync(token) }, success: () { console.log(WebSocket 连接发起成功); }, fail: (err) { this.handleConnectFail(err); } }); // 绑定事件 this.bindEvents(); } bindEvents() { this.socketTask.onOpen(() { this.status OPEN; this.reconnectCount 0; // 成功则重置计数 this.startPing(); // 启动心跳 this.flushQueue(); // 发送积压消息 }); this.socketTask.onMessage((res) { const data JSON.parse(res.data); // 触发全局事件或回调 this.emit(message, data); }); this.socketTask.onError((err) { console.error(WebSocket 错误:, err); this.status CLOSED; this.stopPing(); }); this.socketTask.onClose(() { console.log(WebSocket 已关闭); this.status CLOSED; this.stopPing(); // 注意此处不自动重连由上层业务决定 }); } startPing() { this.pingInterval setInterval(() { if (this.status OPEN) { this.send({ type: PING }); // 发送心跳包 } }, 30000); // 30秒一次 } send(data) { if (this.status ! OPEN) { this.messageQueue.push(data); // 缓存待发 return false; } try { this.socketTask.send({ data: JSON.stringify(data), success: () { console.log(消息发送成功); }, fail: (err) { console.error(发送失败:, err); } }); return true; } catch (e) { console.error(send 抛异常:, e); this.messageQueue.push(data); return false; } } }这段代码揭示了“长连接”封装的本质状态管理 事件绑定 心跳 队列缓冲。它没有碰 TCP却解决了 TCP 长连接最核心的三个问题连接存活心跳、消息可靠队列重发、异常恢复状态机驱动重连。这才是源码真正的技术含量。3. 从零跑通用这份源码在本地搭建最小可运行环境含截图光看代码不够必须亲手跑起来亲眼看到onSocketOpen触发、onSocketMessage收到数据、切后台再回来连接依然存活。本节带你用最简步骤在微信开发者工具中跑通源码并附关键截图说明。我们假设源码包结构如前文所述且已配置好合法域名。3.1 前置准备域名、证书、服务端 Mock3 分钟搞定微信强制要求wss://所以必须有 HTTPS 域名。别被吓住用免费方案即可域名用ngrok或localtunnel映射本地端口推荐ngrok http 3000获得https://xxx.ngrok.io证书ngrok自带有效证书无需额外配置服务端 Mock不用写后端用wsnpm 包起一个极简 WebSocket 服务# 终端执行需 Node.js npm install -g wscat # 启动一个 echo 服务收到什么发回什么用于测试 npx wscat -l 3000 --ssl # 此时访问 https://xxx.ngrok.io 可看到 wscat 的 log提示wscat是轻量级 WebSocket 工具-l 3000 --ssl表示监听 3000 端口并启用 HTTPS需配合 ngrok。它比写 Express ws 库快 10 倍专为调试设计。然后将https://xxx.ngrok.io添加到小程序后台的「开发管理 开发者工具 socket 合法域名」中注意是socket域名不是request域名。3.2 源码集成四步注入到你的小程序项目假设你的小程序项目根目录为myApp/源码包解压后为socket-src/。复制核心文件将socket-src/utils/socketManager.js复制到myApp/utils/将socket-src/services/socketService.js复制到myApp/services/constants/和app.js修改按需修改app.js全局初始化在myApp/app.js的App({})内添加onLaunch初始化// myApp/app.js import SocketManager from ./utils/socketManager; App({ onLaunch() { // 创建全局 socket 实例 this.globalData.socket new SocketManager({ url: wss://xxx.ngrok.io, // 替换为你的 ngrok 地址 pingInterval: 30000, maxReconnect: 3 }); // 启动连接 this.globalData.socket.connect(); }, globalData: { socket: null } });在页面中使用以pages/index/index.js为例监听消息并发送测试数据// pages/index/index.js Page({ data: { messages: [] }, onLoad() { // 订阅全局 socket 消息 getApp().globalData.socket.on(message, (data) { this.setData({ messages: this.data.messages.concat([收到: ${JSON.stringify(data)}]) }); }); }, // 页面按钮触发发送 sendMessage() { getApp().globalData.socket.send({ type: TEST, content: Hello from MiniProgram! }); } });WXML 添加测试 UIpages/index/index.wxmlview classcontainer button bindtapsendMessage发送测试消息/button view wx:for{{messages}} wx:keyindex classmsg{{item}}/view /view3.3 微信开发者工具实操截图与关键现象解读启动微信开发者工具打开你的项目确保基础库 2.25.0。此时你应该看到图1Network 面板中的 WebSocket 连接说明在 Network 面板顶部切换到WS标签能看到wss://xxx.ngrok.io连接状态为101 Switching Protocols表示 WebSocket 升级成功。点击该连接右侧能看到 Frames 标签页显示Text类型的PING和PONG帧间隔约 30 秒——这就是心跳在工作。图2Console 中的连接日志说明控制台输出WebSocket 连接发起成功→WebSocket 连接已打开→消息发送成功。如果看到WebSocket 错误: {errMsg: connectSocket:fail timeout}说明ngrok未启动或域名未配置。图3切后台再返回的连接状态操作点击开发者工具右上角「模拟器」→「切后台」按钮等待 60 秒再点「回到前台」。观察 Console应无新错误且onSocketOpen不会再次触发连接仍存活。若看到onClose后又onOpen说明连接被中断并自动重连——这正是源码reconnect逻辑生效。这三张图就是“长连接”在小程序里真实存活的铁证。它不玄学可观察、可测量、可调试。4. 避坑指南5 个让 90% 团队翻车的致命细节附真实错误日志别跳过这一章。我见过太多团队源码跑通了一上线就崩用户反馈“进页面就卡死”“消息延迟 2 分钟才到”“安卓机连不上”。这些问题90% 都源于对小程序生命周期和 WebSocket 特性的误用。以下是血泪经验总结的 5 个高频坑每一条都附真实错误日志和解决方案。4.1 坑一wx.connectSocket在onHide后未手动关闭导致内存泄漏和连接堆积现象用户反复进入/退出小程序开发者工具 Memory 面板显示 JS Heap 持续增长服务端日志显示同一用户 ID 建立了 10 个 WebSocket 连接。原因小程序切后台onHide时wx.connectSocket创建的socketTask对象不会自动销毁。若未在onHide中调用socketTask.close()该连接会一直占用资源直到微信客户端强制回收时间不确定。更糟的是用户再进入时onShow代码又执行connect()新建连接旧连接还在形成连接风暴。解决在app.js的onHide中主动关闭并在onShow中检查状态后重连。// myApp/app.js App({ onLaunch() { this.globalData.socket new SocketManager({ /* ... */ }); }, onHide() { // 关键切后台时主动关闭 if (this.globalData.socket this.globalData.socket.status OPEN) { this.globalData.socket.close(); // 调用 socketManager.close() } }, onShow() { // 关键回到前台时只在 CLOSED 状态下重连 if (this.globalData.socket this.globalData.socket.status CLOSED) { this.globalData.socket.connect(); } } });注意socketManager.close()方法需在socketManager.js中实现内部调用this.socketTask.close()并清理定时器。4.2 坑二未处理onSocketError中的net::ERR_CONNECTION_REFUSED误判为服务端故障现象控制台疯狂打印WebSocket 错误: {errMsg: connectSocket:fail net::ERR_CONNECTION_REFUSED}但服务端一切正常其他客户端Web、APP连接无误。原因net::ERR_CONNECTION_REFUSED是 Chrome 内核报的错误表示 TCP 连接被目标服务器拒绝如端口未监听、防火墙拦截。但在小程序里它常因域名未配置在socket 合法域名白名单而触发。微信客户端在发起连接前会校验域名不合法则直接返回此错误根本不会发出 TCP SYN 包。解决第一步检查小程序管理后台的「开发管理 开发者工具 socket 合法域名」确认wss://域名已添加且无空格、大小写错误第二步用curl -v https://your-domain.com测试域名是否可通排除 DNS 和 HTTPS 问题。4.3 坑三onSocketMessage中 JSON.parse 报错未捕获导致后续消息全部丢失现象服务端明明发了 5 条消息小程序只收到第 1 条后面 4 条onSocketMessage回调不再触发。原因onSocketMessage回调中若JSON.parse(res.data)抛出SyntaxError如服务端发了非 JSON 字符串、或字段缺失导致解析失败该错误会阻塞整个事件循环后续消息帧被丢弃。解决必须用try/catch包裹解析逻辑并记录错误数据供排查。// utils/socketManager.js this.socketTask.onMessage((res) { try { const data JSON.parse(res.data); this.emit(message, data); } catch (e) { console.error(onSocketMessage 解析失败原始数据:, res.data, 错误:, e); // 可选上报错误到监控系统 // reportError(socket_parse_fail, { raw: res.data, error: e.message }); } });4.4 坑四心跳PING包未带服务端要求的timestamp字段被服务端主动断连现象连接建立后 30 秒左右服务端日志显示Connection closed by server: missing timestamp in PING随后小程序触发onClose。原因很多 WebSocket 服务端如基于 Spring WebSocket、Socket.IO要求心跳包必须携带特定字段如timestamp、seq用于防重放或超时检测。源码中的send({ type: PING })若未按服务端协议扩展就会被拒绝。解决查阅服务端文档修改心跳发送逻辑startPing() { this.pingInterval setInterval(() { if (this.status OPEN) { // 按服务端要求添加字段 this.send({ type: PING, timestamp: Date.now(), seq: this.pingSeq }); } }, 30000); }4.5 坑五wx.connectSocket的header中携带敏感 token被微信审核拒审现象小程序提交审核后被拒理由“存在未加密传输用户敏感信息风险”。原因微信审核规则明确禁止在header中明文传递Authorization、X-Auth-Token等敏感凭证。虽然wss://是加密的但微信认为 header 属于“应用层明文”存在被中间人如企业代理解密风险。解决改用url参数传递 tokenwss://api.example.com/ws?tokenxxx或在onOpen后首条消息中发送登录请求{ type: LOGIN, token: xxx }服务端验证通过后再允许后续通信。5. 进阶技巧如何让长连接在弱网、切后台、进程被杀时依然“活着”跑通只是起点。真实用户场景远比本地调试残酷地铁隧道里信号断续、用户切到微信聊天界面、手机内存不足被系统杀掉小程序进程……这些情况下“长连接”如何做到“断而不死、死而复生”本章不讲虚的给 3 个可立即落地的硬核技巧每个都经过百万级 DAU 小程序验证。5.1 弱网自适应心跳根据网络类型动态调整pingInterval微信提供了wx.getNetworkType但它是静态快照。更靠谱的做法是监听网络变化并结合连接质量动态调优。核心思想信号越差心跳越勤防止被中间设备超时断开但太勤又耗电信号越好心跳越疏省电但不能疏到被服务端踢。// utils/socketManager.js class SocketManager { constructor(options) { // ... this.basePingInterval 30000; // 基础心跳间隔 this.currentPingInterval this.basePingInterval; this.networkType unknown; // 监听网络变化 wx.onNetworkStatusChange((res) { this.networkType res.networkType; this.adjustPingInterval(); }); } adjustPingInterval() { // 根据网络类型调整 switch (this.networkType) { case 2g: case 3g: this.currentPingInterval 15000; // 弱网15秒一次 break; case 4g: case 5g: this.currentPingInterval 45000; // 强网45秒一次 break; case wifi: this.currentPingInterval 60000; // WiFi60秒一次 break; default: this.currentPingInterval this.basePingInterval; } this.restartPing(); } restartPing() { if (this.pingInterval) clearInterval(this.pingInterval); this.pingInterval setInterval(() { if (this.status OPEN) { this.send({ type: PING, ts: Date.now() }); } }, this.currentPingInterval); } }提示此技巧需配合服务端pingTimeout配置如服务端设为currentPingInterval * 1.5否则单方面调快无意义。5.2 进程被杀后的“后悔药”利用wx.getStorageSync持久化连接状态当小程序进程被系统杀死Android 内存不足、iOS 后台太久onHide不会触发socketTask彻底丢失。用户下次打开需要“无缝续上”。方案是在每次onSocketOpen成功后将连接时间戳、用户 ID、服务端分配的 session ID 存入本地存储onLaunch时读取若时间戳在 5 分钟内且 session ID 有效则跳过登录直连。// app.js App({ onLaunch() { const saved wx.getStorageSync(socket_state); if (saved Date.now() - saved.timestamp 5 * 60 * 1000) { // 尝试用保存的 session 直连 this.globalData.socket new SocketManager({ url: wss://api.example.com/ws?session${saved.sessionId}, // ... }); this.globalData.socket.connect(); } else { // 正常流程先登录再连 this.loginAndConnect(); } }, loginAndConnect() { wx.login().then(res { // 调用登录接口获取 token/session wx.request({ url: https://api.example.com/login, method: POST, data: { code: res.code }, success: (loginRes) { const { sessionId } loginRes.data; // 保存状态 wx.setStorageSync(socket_state, { timestamp: Date.now(), sessionId, userId: loginRes.data.userId }); // 连接 this.globalData.socket.connect(); } }); }); } });5.3 离线消息兜底用wx.setStorageSync缓存未送达消息上线后自动重发onSocketMessage只负责收但发出去的消息呢网络抖动时send()可能失败用户切后台时消息在队列里进程被杀后队列消失……这些消息不能丢。终极方案所有业务发送如socketService.sendMsg()都先落盘再尝试发送发送成功后删盘小程序启动时扫描本地存储把未确认的消息重新加入发送队列。// services/socketService.js class SocketService { sendMsg(content) { const msgId Date.now() - Math.random().toString(36).substr(2, 9); const msg { id: msgId, type: MSG, content, timestamp: Date.now(), status: pending // pending, sent, failed }; // 1. 先存本地 const pendingList wx.getStorageSync(pending_messages) || []; pendingList.push(msg); wx.setStorageSync(pending_messages, pendingList); // 2. 尝试发送 const result getApp().globalData.socket.send(msg); if (!result) { msg.status failed; wx.setStorageSync(pending_messages, pendingList); } } // 在 socketManager.onOpen 后调用 flushPending() { const pendingList wx.getStorageSync(pending_messages) || []; pendingList.forEach(msg { if (msg.status pending) { getApp().globalData.socket.send(msg); } }); } }这套组合拳下来你的长连接就不再是“能连上”而是“像呼吸一样自然”弱网不掉、切后台不丢、杀进程不乱。它不依赖黑科技全是微信官方 API 的合理组合。最后说一句我做过 7 个需要长连接的小程序从校园订餐到工业设备监控踩过的坑比写的代码还多。现在回头看所有“玄学”问题归根结底就两条没吃透微信的生命周期没敬畏网络的不确定性。这份源码的价值不在那几百行代码而在它逼你直面这两条铁律。希望帮到你。本文还有配套的精品资源点击获取