简介：这是一份面向微信小程序开发者与网络协议学习者的实战型源码资源，聚焦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 Socket（net.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（微信客户端根据网络类型自动协商）； - 你无法绕过 TLS（
wss://强制加密，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 前置准备：域名、证书、服务端 Mock（3 分钟搞定）
微信强制要求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 添加测试 UI：
pages/index/index.wxml：
<view class="container"> <button bindtap="sendMessage">发送测试消息</button> <view wx:for="{{messages}}" wx:key="index" class="msg">{{item}}</view> </view>3.3 微信开发者工具实操截图与关键现象解读
启动微信开发者工具，打开你的项目，确保基础库 >= 2.25.0。此时你应该看到：
图1：Network 面板中的 WebSocket 连接
说明：在 Network 面板顶部切换到WS标签，能看到wss://xxx.ngrok.io连接状态为101 Switching Protocols，表示 WebSocket 升级成功。点击该连接，右侧能看到 Frames 标签页，显示Text类型的PING和PONG帧，间隔约 30 秒——这就是心跳在工作。图2：Console 中的连接日志
说明：控制台输出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参数传递 token（wss://api.example.com/ws?token=xxx），或在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; // WiFi，60秒一次 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 个需要长连接的小程序，从校园订餐到工业设备监控，踩过的坑比写的代码还多。现在回头看，所有“玄学”问题，归根结底就两条：没吃透微信的生命周期，没敬畏网络的不确定性。这份源码的价值，不在那几百行代码，而在它逼你直面这两条铁律。希望帮到你。
本文还有配套的精品资源，点击获取
