半岛森林做Unity联机项目时，我遇到过最诡异的情况是：客户端连上服务器后，玩家操作着角色，几秒后画面一切正常，但服务器已经单方面把连接当成了“死亡”。更麻烦的是，客户端自己却完全不知道，直到它尝试发一条业务消息时，才突然卡住或者报“连接被关闭”。最后排查一圈才发现，问题不在加密、不在协议、不在序列化，而在我压根没做心跳消息。
这篇就围绕“Unity网络基础实现简单心跳消息”这个最小闭环来聊。我默认你至少用TcpClient写过收发字节流，如果还没有，先花十分钟把Socket编程基础过一遍。这里我会把原理、协议格式、服务端和客户端实现、超时判定、断线重连以及我实际踩过的坑全部展开。适用对象是准备自己写TCP长连接、或者想搞明白为什么自己项目总“假死”的Unity开发者，这套方案不依赖任何收费插件，纯C#就能跑。
1. 为什么要给Unity客户端加心跳：先搞懂连接的本质
1.1 网络连接并不是一条“永远在线”的电话线
很多新手把TCP连接理解成一根实体的电话线，觉得只要两端没有主动断开，连接就一直存在。这是错的。TCP是一条虚拟的、依赖双方不断确认的通道，它要依靠操作系统的协议栈维持状态，而物理链路可能在某个时刻已经中断了，但双方的操作系统还没有感知到。
举一个最贴合的例子：你玩手机游戏时，网络信号在某个地下通道里突然消失，但你的手机没有立刻显示断网，因为系统还在等待无线网卡的报告。如果Wi-Fi没有主动通知系统“链路不可用”，TCP连接的状态在你看不到的地方仍然是ESTABLISHED。等过了几十秒，系统尝试重传数据、发现没有ACK，这才真正把连接标记为断开。在服务端视角，这个连接就一直占着文件描述符、占着内存，直到超时才被清理。
所以心跳消息的本质不是“传输业务数据”，而是一种主动探测机制——客户端定期给服务端发一条很小的消息，服务端收到后回一条响应，两端都通过“上一次成功通信的时间”来判断对方是否还活着。
1.2 没有心跳时你会遇到哪些诡异问题
凡是自己用TCP写过长连接的人，基本都遇到过下面这些情况：
- 玩家拔掉网线或强制关闭进程，服务端不会第一时间知道，这条连接会一直挂在连接列表里；
- 服务端主动重启后，旧的客户端连接进入半开状态，客户端发数据时才发现连接损坏，但业务上已经“卡死”了一会儿；
- 客户端长时间没发数据，中间路由器或防火墙把空闲连接给回收了，但两端都没收到任何通知；
- 高并发场景下，服务器积累了大量的“僵尸连接”，占用了连接数上限，新玩家反而连不进来。
这些问题如果只用TCP自带的KeepAlive，并不能完全解决，因为TCP KeepAlive默认间隔是2小时，而且它只能保证“TCP层还通”，不能保证“应用层还正常”。应用层心跳则是真正适合游戏业务的手段，因为你可以自己控制间隔、超时阈值，还可以在心跳包内附带客户端状态、时间戳等信息。
1.3 心跳和“连接超时”是什么关系
心跳是手段，超时判定是目的。客户端每过一段时间发一个Ping，服务端必须在约定时间内回一个Pong，客户端在另一个约定时间内没收到，就认为连接已经不在可用状态。
这里有两个参数需要区分：
- 发送间隔：客户端每隔多久发一次心跳；
- 超时时间：客户端最多等待多久没收到Pong就判定断线。
这两个参数不是一回事，也不是随便拍的。如果发送间隔是30秒，但超时时间也设置成30秒，那么只要服务器在下一个心跳前稍微延迟一下响应，客户端就可能误判。通常建议超时时间至少是发送间隔的3倍，比如间隔10秒，超时时间30秒。如果业务要求快速感知断线，可以把间隔调成3秒、超时调成10秒，但这样会带来更多的心跳包，对服务器压力也更大。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 协议设计：一个心跳包应该长什么样
2.1 从零定义消息格式
不要先写代码，先把字节格式定下来。心跳消息看似简单，但它是整个协议的一部分，将来还要扩展业务消息。如果一开始格式草率，后面会被粘包、解析问题折磨很久。
我常用的方案是“消息头 + 消息体”结构。消息头固定长度，用前4个字节表示整个消息的长度（不包括长度字段本身），再用1个字节表示消息类型，消息体按类型解析。以心跳为例：
- 消息类型为1（Heartbeat请求）
- 消息体可以为空，也可以放一个客户端ID和时间戳
这样一个简单的心跳包可能长这样：
code复制[4字节长度(整个消息长度)][1字节类型][4字节客户端ID][8字节时间戳]
这种格式带来的好处是：接收方只要先读4个字节拿到长度，再根据长度读取完整消息体，就能避免粘包和半包问题。如果是用字符串或Json，反而不好判断一条消息的边界在哪。
2.2 用ByteBuffer还是Json？聊一聊序列化选型
很多Unity新手在序列化上直接选JsonUtility或LitJson，图省事。但心跳这种高频小包，我建议用二进制序列化。理由很简单：Json要Convert成字符串，然后编码成字节，流程长、体积大，而且也不方便处理二进制消息边界。
Unity默认的BinaryFormatter也能用，但跨平台、跨版本时会有坑，而且它的二进制流里包含了类型信息，包体会膨胀。我自己在做网络层时更倾向于手动管理字节顺序，或者写一个极简的ByteBuffer工具类。
如果你用的网络库自带序列化（比如Mirror的MessageBase），那就不用手动处理。但现在我们聊的是“基于基础的TcpClient实现”，所以我更推荐手动拼一个简单的字节工具，这样你能完全掌控每个消息的结构。
一个极简的ByteBuffer可以只支持写int、写long、写byte[]和读对应类型。因为C#的二进制格式在不同平台上可能遇到大小端问题，所以在写协议时建议统一用大端序，也就是网络字节序。
2.3 处理粘包和半包：一个TCP必然面对的坎
这是TCP新手最容易翻车的地方。TCP是流式协议，它不保证你调用一次Send发送的数据，在另一端会通过一次Receive完整收到。也就是说，客户端连续发送两个心跳包时，服务端可能一次性收到两个包的内容合并在一起，这就是粘包；也可能只收到一个包的一半，另一半要等下一段数据到来，这就是半包。
没有长度前缀，你根本没法判断缓冲区的数据到底是一条消息还是多条消息，或者是一条不完整的消息。
处理逻辑并不复杂，在接收缓冲区里循环解析：
- 如果缓冲区可读字节数小于4，先等更多数据；
- 读取长度字段，知道这条消息总共多少字节；
- 如果可读字节数小于长度字段声明的值，说明还没收完，继续等；
- 从缓冲区中取出一个完整消息，交给消息处理器；
- 回到第1步，继续处理剩余字节。
所以协议里安排“4字节长度头”不是可有可无的，它是处理粘包半包的基础设施。你甚至可以在消息头里再加一个2字节的魔法数，用来校验是不是正确的协议版本。不过心跳包本身长度很短，加太多字段反而浪费，够用就行。
3. 服务端实现：C# TcpListener做最简心跳回应
3.1 服务端框架思路
如果你只是想验证心跳逻辑，最简单的服务端可以不用上Mirror或者DotNetty这种重框架，直接用一个TcpListener就能跑通。
服务端主要做三件事：
- 监听端口，接受客户端连接；
- 为每个连接创建一个接收线程（或异步任务），循环读取消息；
- 维护一个
ConcurrentDictionary<连接ID, 客户端状态>，状态里记录LastHeartbeatTime。
加一个后台清理线程，每隔几秒扫描一次所有客户端，如果当前时间减去LastHeartbeatTime超过阈值，就断开连接并释放资源。
这里要特别注意线程安全。服务端处理每个连接的线程不同，多个线程都会访问字典，所以不能用一个普通的Dictionary<TKey, TValue>，要用ConcurrentDictionary，或者用lock保护。
3.2 接收心跳、应答Pong、清理超时连接
服务端收到一个长度为固定最小值的消息时，首先解析消息类型。如果是心跳请求，那就更新该客户端的LastHeartbeatTime，然后立刻回发一个Pong响应。Pong的消息类型建议设置为2，消息体可以直接回显客户端发来的时间戳，方便客户端测量往返延迟。
整个处理流程的伪代码如下：
csharp复制// 解析出的消息：type=1, clientId=xxx, timestamp=xxx
if (type == 1)
{
var state = clients[clientId];
state.LastHeartbeatTime = DateTime.UtcNow;
// 回Pong
byte[] pong = BuildMessage(2, clientId, timestamp);
state.Socket.Send(pong);
}
清理线程的逻辑就一句话：
csharp复制foreach (var kvp in clients)
{
var state = kvp.Value;
if ((DateTime.UtcNow - state.LastHeartbeatTime).TotalSeconds > 60)
{
state.Socket.Close();
clients.TryRemove(kvp.Key, out _);
}
}
这个后台扫描的间隔不一定要很频繁，比如10秒扫一次就够了，不必每秒扫。心跳的精度不要求秒级响应，有些场景下延迟几秒清理完全可接受。
3.3 服务端心跳超时参数怎么定
服务端的超时时间必须大于客户端的心跳发送间隔。如果客户端每10秒发一次心跳，服务端至少要在30秒以上没收到心跳时才判定超时。为什么？因为网络上偶尔会丢包或延迟，TCP有重传机制，但你应用层不一定能立刻拿到一次心跳。设置3倍间隔是相对平衡的经验值。
如果业务允许，服务端也可以设置两级超时：第一级是“警告超时”，超过之后给客户端发一个ping请求，如果客户端在下一个阈值内没回复，再断开。这种方式能减少误杀，但实现复杂度也更高。大多数简单项目不需要这么做。
4. Unity客户端实现：TcpClient + 协程/异步的心跳发送
4.1 建立连接与状态管理
Unity客户端我建议用System.Net.Sockets.TcpClient，因为它是Unity最基本的网络对象。连接可以用异步方法ConnectAsync，避免阻塞主线程。连接之前要设置一个连接超时，不然在网段不通的情况下，TcpClient.Connect可能卡住很长时间。
连接状态我建议用一个枚举管理：
csharp复制public enum ConnectionState
{
Disconnected,
Connecting,
Connected,
WaitingPong,
Reconnecting
}
每次发送心跳后，把状态设置为WaitingPong，收到Pong后再切回Connected。这样你可以很清楚地知道当前连接是否健康。
需要注意，不要在Update里直接调用阻塞式的Send和Receive，因为Unity主线程不能卡；也不要在连接状态转换时直接修改正在被其他线程访问的Socket。推荐的做法是把网络收发放到后台任务，用线程安全队列把收到的消息转回主线程处理。
4.2 心跳发送的三种节奏方案
心跳发送的节奏设计上有几个流派，我分别说一下：
- 固定间隔发送：最简单，写一个协程，每10秒发一次，只要连接还在就不断发。适合大多数项目。
- 固定间隔 + 超时检测：在固定间隔基础上，客户端记录上次收到Pong的时间，超过阈值还没收到就判定断线并触发重连。这个最稳。
- 动态心跳：空闲时不发或低频发，检测到玩家进入战斗或需要对实时性要求高的场景时提高心跳频率。这个适合复杂项目，但基础实现不推荐。
我建议从方案二开始做。发送间隔10秒，超时时间30秒，这样客户端的网络开销极小，又能保证服务器能在大约30秒内发现客户端异常。
写协程时要注意，如果你的网络线程和主线程是分离的，千万不要在协程里直接操作Socket的收发，协程只是用来控制时间节奏，真正的发送动作应该通过一个线程安全方法调用。
4.3 用MonoBehaviour协程还是Thread
在Unity里，最简单的方案就是继承MonoBehaviour，在Start里启动一个协程来发送心跳。协程的问题在于它受主线程影响，如果游戏挂起或者主线程卡顿，心跳也会卡住，这对检测断线反而不是坏事，因为客户端卡死被服务器断开是合理的。
另一种方案是把网络接收循环放到一个独立线程里，类似：
csharp复制Thread receiveThread = new Thread(ReceiveLoop);
receiveThread.IsBackground = true;
receiveThread.Start();
这个线程里做BeginReceive或同步Receive循环。心跳发送则仍然放在主线程协程里。两者配合时，注意收包回调是通过线程触发的，如果要更新Unity的UI或游戏状态，需要用ConcurrentQueue缓存事件，再在Update里消费。
我自己的经验是：小项目先用协程+异步收发就够，但如果你以后要扩展到大量在线玩家，才需要认真设计网络线程模型。别一开始就上复杂模型，否则排查问题的难度会成倍增加。
5. 断线检测与自动重连：心跳真正的价值
5.1 超时未收到Pong之后怎么办
当客户端在超时时间内没有收到Pong，你不能直接假设服务器已经关了，可能只是网络抖动。此时正确的做法是：把连接置为Reconnecting状态，关闭旧Socket，释放资源，然后进入重连流程。
直接尝试在旧连接上继续收发是常见的坑。因为Socket一旦出错，状态就已经损坏，再调Send只会反复抛SocketException。所以果断关闭它，重新走一遍“连接-握手-心跳”流程。
关闭旧连接时记得将TcpClient.Close()和NetworkStream.Dispose()都调用一下，否则端口和文件句柄可能释放不及时。
5.2 指数退避重连算法的落地
重连不能太激进。如果服务器因为某种原因崩溃重启，而所有客户端都在同一时间疯狂重连，那服务器可能连启动都困难。
指数退避的意思是：第一次重连等待1秒，第二次2秒，第三次4秒，达到最大上限后就不再增长，比如最多30秒。同时可以加一些随机抖动，免得所有客户端在同一个时间点尝试连接。
实现起来并不复杂：
csharp复制private IEnumerator ReconnectLoop()
{
int retryCount = 0;
float baseDelay = 1f;
float maxDelay = 30f;
while (state == ConnectionState.Reconnecting && !stopFlag)
{
float delay = Mathf.Min(maxDelay, baseDelay * Mathf.Pow(2f, retryCount));
delay += Random.Range(0f, 1f);
yield return new WaitForSeconds(delay);
if (TryConnect())
{
retryCount = 0;
state = ConnectionState.Connected;
yield break;
}
retryCount++;
}
}
重连成功后不要忘记重新启动心跳发送协程。很多人的Bug就是重连成功了一次，但心跳协程已经停掉了，导致连接很快又被判定为超时。
5.3 断开一瞬间UI应该怎么处理
断线时如果直接弹一个“连接已断开”的窗口，体验很生硬。更好的做法是：
- 在连接状态变成
Reconnecting时，UI显示一个“连接中...”的遮罩或小图标，但不要阻塞玩家操作； - 如果持续几秒无法重连，再弹窗询问“是否重试”；
- 如果重连成功，把因为断线期间缓存的输入操作丢弃，避免发送失败导致状态错乱。
在Unity主线程里，你可以用一个UnityAction事件来通知UI层，不要直接在其他线程里操作Text或Button。
6. 实测中的坑与性能细节
6.1 心跳风暴是怎么产生的
你知道“心跳风暴”吗？就是大量客户端同时发送心跳，导致服务器瞬间处理不过来。常见场景是服务器完成一次重启，所有存活的客户端检测到断开，然后在同一秒全部重连，重连成功后又在同一时刻发出第一批心跳。
解决思路有两个：第一，重连算法里加随机抖动，避免所有客户端同频重连；第二，客户端发送心跳时，设定一个随机偏移，比如第一次心跳在连接成功后0到3秒内随机发送，之后才按固定间隔走。
服务器端也可以做限流：如果同一IP、同一时间段内收到的连接请求过多，可以拒绝或延迟处理。不过这些属于服务器防护范畴，心跳阶段先保证客户端侧不制造风暴就够了。
6.2 时间戳用DateTime.Now还是Environment.TickCount
在频繁的心跳消息里，时间戳用于计算RTT（往返延迟）或判断消息新鲜度。这里有个隐蔽的坑：DateTime.Now在系统时间被手动修改或NTP校时发生跳变时，会出现时间倒退或向前跳跃，如果用它来判断超时，可能导致误判。
更稳妥的是使用Environment.TickCount或Environment.TickCount64，它是系统开机后的毫秒数，单调递增，不受系统时间调整影响。Unity里你也可以用Time.realtimeSinceStartup，但它依赖Unity的时钟，网络线程调用时未必合适。
在服务端写超时检查时，同样建议使用Environment.TickCount或Stopwatch.GetTimestamp()，不要依赖DateTime.UtcNow。
6.3 本地测通但局域网不行的排查思路
很多人在本机测试时一切正常，但放到局域网就有客户端连不上或者频繁断开。这种问题八成不在心跳逻辑，而是底层的网络通信问题。
排查顺序大概是这样的：
- 确认服务器监听的是
0.0.0.0，而不是127.0.0.1；本机测试可以连127.0.0.1，但局域网客户端连不上通常就是这个原因。 - 检查防火墙是否放行了对应端口，TCP入站规则要显式放行。很多开发者只关了Windows防火墙，但装了第三方安全软件的话，也要一起检查。
- 用
telnet 服务器IP 端口测试端口通不通；通的话说明底层网络OK，不通则从网络环境找原因。 - 查看服务器是否设置了连接超时或空闲回收，某些路由器的NAT老化时间也可能导致空闲连接被回收，这就回到心跳消息的作用：通过周期性数据保活，尽量避免中间设备把连接静默断开。
另外，Unity编辑器的重载和播放模式下，OnApplicationQuit不一定被可靠调用，导致端口没有完全释放。频繁进出Play模式时，可能遇到“端口被占用”，这时候在编辑器里重启或等待一段时间就好了。
6.4 不要忽略协议解析的鲁棒性
很多简单实现只处理“消息完整到达”的情况，但真实网络环境里数据到达是碎片化的。你的接收缓冲区必须足够健壮：当收到残缺消息时，要保留半包数据继续等待，而不是清空缓冲区。如果你发现客户端心跳总是被服务器正确接收，但服务器日志里经常出现解析异常，那大概率是半包处理写错了。
我自己的一个教训是：把接收缓冲区的消费逻辑和消息解析逻辑混在一起，结果每次数据到达后都新建一个临时数组，把后半段数据丢了。后来改成用MemoryStream或Queue<byte>持续累积，解析完一部分就移除一部分，才算稳定。
心跳包这么小的消息都会遇到半包，大消息更容易。所以协议解析的鲁棒性是所有网络模块的地基，别贪快。
最后再分享一个小细节：心跳消息虽然叫“心跳”，但它不止能传一个心跳标志。你可以在心跳包和Pong包里附带客户端的当前帧号、延迟、时间戳，甚至是简单的状态同步。这样当你以后需要做在线人数统计、延迟观察、客户端卡顿检测时，很多数据都能直接从心跳日志里拿到。我用这套最简方案跑过几百人的压力测试，只要协议设计合理、参数不夸张，心跳的开销完全可以忽略不计。希望这篇能帮你少走点弯路，把Unity网络基础真正踩扎实。