1. 项目概述为什么Unity需要WebSocket通信在游戏开发尤其是需要实时交互的联机游戏、实时数据看板或者多人在线应用中客户端与服务端之间的通信是核心骨架。传统的HTTP协议基于请求-响应的模式对于需要服务端主动、高频向客户端推送数据的场景比如聊天消息、玩家位置同步、实时比分更新就显得力不从心。你总不能让客户端每秒发几十次“轮询”请求去问服务端“有数据吗”这既浪费带宽也增加延迟。这就是WebSocket登场的时候。它建立在TCP之上提供全双工、长连接的通信通道。连接一旦建立客户端和服务端就可以在任何时刻、主动地向对方发送数据就像在两者之间架起了一条双向的数据高速公路。对于Unity这类实时性要求高的客户端WebSocket是实现流畅、低延迟实时通信的首选方案。而Fleck是一个用C#编写的轻量级、高性能的WebSocket服务器库。它不依赖于庞大的IIS或ASP.NET Core框架可以非常简洁地嵌入到你的控制台应用或Windows服务中快速构建起WebSocket服务端。将Unity客户端与基于Fleck的C#服务端结合就构成了一套高效、可控、跨平台的实时通信解决方案。这套方案特别适合中小型实时应用、原型开发、内部工具以及那些希望完全掌控通信逻辑的开发者。2. 核心思路与架构设计2.1 技术选型为什么是Fleck Unity选择Fleck作为服务端主要基于以下几点考量轻量与简洁Fleck的API设计非常直观几行代码就能启动一个WebSocket服务器。它没有复杂的配置和依赖让你能快速聚焦于业务逻辑。性能与可控性作为纯C#实现的库它在.NET环境下运行高效。你可以完全控制连接的生命周期、消息的处理逻辑方便进行深度定制和优化。与Unity的天然亲和力Unity支持C#作为主要脚本语言。服务端也用C#开发意味着前后端可以共享一些数据模型、序列化工具如Newtonsoft.Json/System.Text.Json甚至部分工具类代码减少上下文切换成本提升开发效率。整个架构的核心思想是解耦与异步。服务端Fleck作为一个独立的进程运行负责维护所有客户端的连接、验证身份、广播或转发消息。Unity客户端在启动时连接到指定的WebSocket服务器地址如ws://127.0.0.1:8181之后便通过这个长连接通道与服务端进行双向通信。2.2 通信协议与数据格式设计WebSocket传输的是原始的二进制byte[]或文本string数据。为了在Unity和服务端之间传递结构化的信息比如一个包含玩家ID、位置坐标、动作类型的复杂对象我们需要定义一套双方都能理解的“语言”即数据格式。常见的格式有以下几种本次实战将涵盖它们纯文本Plain Text最简单的格式用于传输指令、状态码或简单的字符串消息。例如PLAYER_JUMP。JSONJavaScript Object Notation最通用、最灵活的结构化数据格式。易于人阅读和编写也易于机器解析和生成。几乎所有的编程语言都有成熟的JSON库支持。它是复杂数据交换的首选。二进制Binary当需要传输大量数据如图片、音频片段、密集的网格数据或对传输效率和隐私性有极高要求时直接使用二进制格式。它体积最小但需要前后端严格约定字节序列的结构。在我们的设计中每条消息可以包含一个“消息头”来标识其数据类型方便接收方进行解析分发。例如消息可以是这样的结构{ type: player_move, data: { playerId: player_001, position: {x: 10.5, z: 20.3}, timestamp: 1627890123456 } }或者对于二进制消息前几个字节可以是一个整数用来表示后续数据的类型。3. 服务端Fleck搭建与核心实现3.1 环境准备与项目创建首先你需要一个.NET开发环境。这里以.NET 6的控制台应用为例。使用Visual Studio 2022或JetBrains Rider创建一个新的“控制台应用”项目目标框架选择.NET 6.0或更高版本。通过NuGet包管理器为项目安装Fleck库。你可以在包管理器控制台中执行命令Install-Package Fleck。3.2 基础WebSocket服务器搭建Fleck服务器的核心是WebSocketServer类和IWebSocketConnection接口。下面是一个最基础的服务器实现它监听本地8181端口并处理客户端的连接、接收消息和断开事件。using Fleck; using System; using System.Collections.Generic; using System.Linq; namespace UnityWebSocketServer { class Program { // 存储所有活跃连接的客户端 static ListIWebSocketConnection allClients new ListIWebSocketConnection(); static void Main(string[] args) { // 1. 创建WebSocket服务器实例指定监听地址和端口 var server new WebSocketServer(ws://0.0.0.0:8181); server.Start(socket { // 2. 连接建立时的回调 socket.OnOpen () { Console.WriteLine($客户端已连接连接ID: {socket.ConnectionInfo.Id}); allClients.Add(socket); // 可以在这里进行身份验证等操作 }; // 3. 接收到客户端消息时的回调 socket.OnMessage message { Console.WriteLine($来自 {socket.ConnectionInfo.Id} 的消息: {message}); // 默认处理为文本消息这里进行简单广播 BroadcastMessage($客户端 {socket.ConnectionInfo.Id} 说: {message}, socket); }; // 4. 连接关闭时的回调 socket.OnClose () { Console.WriteLine($客户端断开连接: {socket.ConnectionInfo.Id}); allClients.Remove(socket); }; // 5. 发生错误时的回调 socket.OnError exception { Console.WriteLine($客户端 {socket.ConnectionInfo.Id} 发生错误: {exception.Message}); allClients.Remove(socket); }; }); Console.WriteLine(WebSocket 服务器已启动按任意键退出...); Console.ReadKey(); } // 简单的广播方法向除发送者外的所有客户端发送消息 static void BroadcastMessage(string message, IWebSocketConnection sender) { var clientsToSend allClients.Where(client client ! sender).ToList(); foreach (var client in clientsToSend) { client.Send(message); } } } }注意ws://0.0.0.0:8181中的0.0.0.0表示监听所有可用的网络接口。在生产环境中你可能需要配置具体的IP或域名并考虑防火墙设置。3.3 多格式消息处理机制上面的例子只处理了文本消息。现在我们来增强它使其能智能处理JSON和二进制格式。首先定义一个简单的消息协议枚举和对应的数据模型。// MessageType.cs namespace UnityWebSocketServer { public enum MessageType { Text 0, Json 1, Binary 2 } } // SimpleMessage.cs (用于JSON序列化/反序列化) public class SimpleMessage { public string Command { get; set; } public object Data { get; set; } }然后修改OnMessage回调实现多格式分发。我们约定客户端发送的消息第一个字符或第一个字节用于标识消息类型。T或0x00(byte): 文本J或0x01(byte): JSONB或0x02(byte): 二进制以下是服务端处理逻辑的升级版socket.OnMessage message { // 处理文本消息Fleck的OnMessage直接提供string ProcessTextMessage(message, socket); }; socket.OnBinary bytes { // 处理二进制消息 ProcessBinaryMessage(bytes, socket); }; // 处理文本消息的函数 static void ProcessTextMessage(string fullMessage, IWebSocketConnection socket) { if (string.IsNullOrEmpty(fullMessage)) return; char prefix fullMessage[0]; string content fullMessage.Substring(1); // 去除前缀 switch (prefix) { case T: // 纯文本 Console.WriteLine($[文本]来自 {socket.ConnectionInfo.Id}: {content}); HandleTextCommand(content, socket); break; case J: // JSON Console.WriteLine($[JSON]来自 {socket.ConnectionInfo.Id}: {content}); try { // 使用System.Text.Json或Newtonsoft.Json反序列化 var jsonMsg System.Text.Json.JsonSerializer.DeserializeSimpleMessage(content); HandleJsonMessage(jsonMsg, socket); } catch (Exception ex) { Console.WriteLine($JSON解析失败: {ex.Message}); socket.Send(ERROR: Invalid JSON format.); } break; default: Console.WriteLine($未知的文本消息前缀: {prefix}); break; } } // 处理二进制消息的函数 static void ProcessBinaryMessage(byte[] bytes, IWebSocketConnection socket) { if (bytes null || bytes.Length 1) return; byte prefix bytes[0]; byte[] content new byte[bytes.Length - 1]; Array.Copy(bytes, 1, content, 0, content.Length); switch (prefix) { case 0x02: // 二进制数据 Console.WriteLine($[二进制]来自 {socket.ConnectionInfo.Id}, 长度: {content.Length} bytes); HandleBinaryData(content, socket); break; default: Console.WriteLine($未知的二进制消息前缀: {prefix}); break; } } // 示例处理函数 static void HandleTextCommand(string cmd, IWebSocketConnection socket) { if (cmd PING) { socket.Send(TPONG); // 回复一个带前缀的PONG } } static void HandleJsonMessage(SimpleMessage msg, IWebSocketConnection socket) { Console.WriteLine($收到命令: {msg.Command}); // 根据Command执行不同逻辑例如广播给其他玩家 if (msg.Command CHAT) { var broadcastMsg new SimpleMessage { Command CHAT, Data new { sender socket.ConnectionInfo.Id, text msg.Data } }; string jsonToSend J System.Text.Json.JsonSerializer.Serialize(broadcastMsg); BroadcastMessage(jsonToSend, socket); } } static void HandleBinaryData(byte[] data, IWebSocketConnection socket) { // 例如处理一张图片的二进制数据 Console.WriteLine($收到二进制数据首个字节: {data[0]}); // 这里可以解码、存储或转发数据 }实操心得在实际项目中消息协议的设计至关重要。你可以使用更复杂的结构比如固定长度的消息头包含消息类型、版本、负载长度等字段。使用像MessagePack或Protobuf这样的二进制序列化协议能获得比JSON更极致的性能和更小的体积特别适合对实时性要求极高的游戏状态同步。3.4 连接管理与心跳机制长连接面临的一个问题是判断对方是否还“活着”。网络波动、客户端崩溃都可能导致连接实际已失效但服务端并未收到关闭帧。因此需要引入“心跳机制”。心跳通常由客户端定期如每30秒向服务端发送一个特定的轻量级消息如TPING。服务端收到后立即回复如TPONG。如果服务端在连续多个周期内未收到某个客户端的心跳则判定其连接超时主动关闭该连接。在Fleck中我们可以为每个连接IWebSocketConnection附加一个最后活跃时间戳并启动一个后台定时器来检查。// 在Program类中增加一个字典来记录连接的最后活跃时间 static DictionaryGuid, DateTime clientLastActiveTime new DictionaryGuid, DateTime(); static System.Timers.Timer heartbeatTimer new System.Timers.Timer(30000); // 30秒检查一次 // 在Main方法中启动定时器 heartbeatTimer.Elapsed CheckHeartbeat; heartbeatTimer.AutoReset true; heartbeatTimer.Enabled true; // 在OnOpen中初始化时间 socket.OnOpen () { Console.WriteLine($客户端已连接连接ID: {socket.ConnectionInfo.Id}); allClients.Add(socket); clientLastActiveTime[socket.ConnectionInfo.Id] DateTime.Now; }; // 在收到任何消息包括PING时更新活跃时间 // 在ProcessTextMessage的HandleTextCommand中处理PING if (cmd PING) { clientLastActiveTime[socket.ConnectionInfo.Id] DateTime.Now; // 更新活跃时间 socket.Send(TPONG); } // 心跳检查函数 static void CheckHeartbeat(object sender, System.Timers.ElapsedEventArgs e) { var now DateTime.Now; var timeoutClients new ListIWebSocketConnection(); foreach (var client in allClients) { if (clientLastActiveTime.TryGetValue(client.ConnectionInfo.Id, out DateTime lastActive)) { if ((now - lastActive).TotalSeconds 90) // 超过90秒无活动 { Console.WriteLine($客户端 {client.ConnectionInfo.Id} 心跳超时即将关闭连接。); timeoutClients.Add(client); } } else { // 没有记录也视为异常 timeoutClients.Add(client); } } foreach (var client in timeoutClients) { client.Close(); // Close方法会触发OnClose回调在那里清理资源 } } // 在OnClose中清理记录 socket.OnClose () { Console.WriteLine($客户端断开连接: {socket.ConnectionInfo.Id}); allClients.Remove(socket); clientLastActiveTime.Remove(socket.ConnectionInfo.Id); // 重要移除记录 };4. Unity客户端实现详解4.1 Unity WebSocket客户端选型Unity本身不提供原生的WebSocket客户端类。我们需要借助第三方库。常见的选择有Native WebSocket一些基于.NET标准库System.Net.WebSockets的封装如NativeWebSocket。性能较好但可能需要处理线程问题。WebSocket-Sharp一个成熟的C# WebSocket库在Unity中也很流行。Best HTTP/WebSocketUnity Asset Store上的付费插件功能强大且稳定。Unity官方包实验性com.unity.websockets但目前可能还不够稳定。为了保持与教程一致性和简便性我们使用一个在GitHub上流行的开源库NativeWebSocket。你可以通过Unity的Package Manager的“Add package from git URL”功能添加https://github.com/endel/NativeWebSocket.git。4.2 连接管理与消息发送在Unity中创建一个空的GameObject并挂载一个名为WebSocketClientManager的脚本。using NativeWebSocket; using System; using System.Text; using UnityEngine; public class WebSocketClientManager : MonoBehaviour { private WebSocket websocket; public string serverAddress ws://127.0.0.1:8181; // 修改为你的服务器地址 async void Start() { // 1. 创建WebSocket连接 websocket new WebSocket(serverAddress); // 2. 注册事件回调 websocket.OnOpen OnWebSocketOpen; websocket.OnMessage OnWebSocketMessageReceived; websocket.OnError OnWebSocketError; websocket.OnClose OnWebSocketClosed; // 3. 开始连接 await websocket.Connect(); } void OnWebSocketOpen() { Debug.Log(WebSocket连接成功); // 连接成功后开始发送心跳 InvokeRepeating(nameof(SendHeartbeat), 30f, 30f); // 30秒后开始每30秒一次 // 发送一条测试文本消息 SendTextMessage(THello Server from Unity!); // 发送一条JSON消息 SendJsonMessage(LOGIN, new { username UnityPlayer, level 5 }); } void OnWebSocketMessageReceived(byte[] bytes) { // 收到二进制消息NativeWebSocket统一用byte[]接收 // 我们需要根据服务端的协议来解析第一个字节 if (bytes.Length 0) return; byte prefix bytes[0]; string content Encoding.UTF8.GetString(bytes, 1, bytes.Length - 1); // 注意这里假设后续是UTF8文本。纯二进制数据需另处理。 switch (prefix) { case (byte)T: // 文本 Debug.Log($[文本]来自服务器: {content}); break; case (byte)J: // JSON Debug.Log($[JSON]来自服务器: {content}); // 反序列化JSON内容 try { var jsonNode JsonUtility.FromJsonSimpleMessageWrapper(content); ProcessServerCommand(jsonNode); } catch (Exception e) { Debug.LogError($JSON解析错误: {e.Message}); } break; case 0x02: // 二进制 Debug.Log($[二进制]来自服务器长度: {bytes.Length - 1}); ProcessBinaryData(bytes, 1); // 从索引1开始是数据 break; default: Debug.LogWarning($未知消息前缀: {prefix}); break; } } // 辅助类用于解析顶层是Command和Data结构的JSON [System.Serializable] public class SimpleMessageWrapper { public string Command; public string Data; // 注意JsonUtility需要字符串复杂Data可以再嵌套解析 } void ProcessServerCommand(SimpleMessageWrapper msg) { switch (msg.Command) { case CHAT: Debug.Log($收到聊天消息: {msg.Data}); break; // ... 处理其他命令 } } void ProcessBinaryData(byte[] data, int startIndex) { // 处理二进制数据例如解码纹理 // Texture2D tex new Texture2D(2, 2); // if (tex.LoadImage(data, startIndex)) { ... } } void OnWebSocketError(string errorMsg) { Debug.LogError($WebSocket错误: {errorMsg}); } void OnWebSocketClosed(WebSocketCloseCode closeCode) { Debug.Log($WebSocket连接关闭代码: {closeCode}); CancelInvoke(nameof(SendHeartbeat)); // 停止心跳 } // 发送消息的公共方法 public void SendTextMessage(string text) { if (websocket?.State WebSocketState.Open) { // 添加前缀T string messageToSend T text; websocket.SendText(messageToSend); } } public void SendJsonMessage(string command, object data) { if (websocket?.State WebSocketState.Open) { var msg new { Command command, Data data }; string json JsonUtility.ToJson(msg); // 添加前缀J string messageToSend J json; websocket.SendText(messageToSend); } } public void SendBinaryMessage(byte[] data) { if (websocket?.State WebSocketState.Open data ! null) { // 构建带前缀的字节数组 byte[] messageToSend new byte[data.Length 1]; messageToSend[0] 0x02; // 二进制前缀 Array.Copy(data, 0, messageToSend, 1, data.Length); websocket.Send(messageToSend); } } // 心跳函数 void SendHeartbeat() { SendTextMessage(PING); } void Update() { // NativeWebSocket需要在主线程调用DispatchMessageQueue来处理回调 #if !UNITY_WEBGL || UNITY_EDITOR if (websocket ! null) { websocket.DispatchMessageQueue(); } #endif } async void OnDestroy() { // 脚本销毁时关闭WebSocket连接 CancelInvoke(); if (websocket ! null) { await websocket.Close(); } } }4.3 多格式数据发送实战在Unity中发送不同格式的数据非常直观文本直接拼接字符串发送。JSON使用JsonUtility.ToJsonUnity内置性能好但功能有限或Newtonsoft.Json需安装功能强大将对象序列化为字符串后发送。二进制将任何数据Texture2D的EncodeToPNG/JPGAudioClip的GetData或自定义的结构体序列化后的字节数组准备好添加前缀后发送。例如发送玩家位置信息JSONpublic void SendPlayerPosition(Vector3 position) { SendJsonMessage(PLAYER_MOVE, new { x position.x, y position.y, z position.z }); }例如发送一个截图二进制public void SendScreenshot() { StartCoroutine(CaptureAndSendScreenshot()); } System.Collections.IEnumerator CaptureAndSendScreenshot() { yield return new WaitForEndOfFrame(); Texture2D screenTex ScreenCapture.CaptureScreenshotAsTexture(); byte[] pngBytes screenTex.EncodeToPNG(); Destroy(screenTex); SendBinaryMessage(pngBytes); }注意事项JsonUtility是Unity自带的序列化工具但它不支持字典、不支持私有字段、需要[Serializable]特性。对于复杂的数据结构强烈建议使用Newtonsoft.Json即Json.NET你可以通过Unity的Package Manager搜索“Newtonsoft Json”来安装。5. 高级主题与性能优化5.1 数据压缩与加密当传输频率高或数据量大时如多人游戏的实时状态压缩可以显著节省带宽。压缩可以对JSON字符串或二进制负载进行压缩。常用的有GZipStream或第三方库如LZ4。在发送前压缩接收后解压。需要在消息协议中增加一个标志位来指示数据是否被压缩。加密如果传输敏感信息需要加密。可以在应用层使用AES等对称加密算法。客户端和服务端共享一个密钥密钥交换本身是一个安全课题可能需要通过HTTPS/WSS首次连接协商。更简单的方式是直接使用WSSWebSocket Secure它相当于WebSocket over TLS/SSL在传输层提供加密无需在应用层处理。5.2 连接重连与状态同步网络不稳定是常态。一个健壮的客户端必须具备自动重连能力。检测断开在OnWebSocketClosed回调中如果不是主动关闭如退出游戏则触发重连逻辑。指数退避重连重连间隔应逐渐增加如1秒2秒4秒8秒...直到一个最大值避免在服务端短暂故障时疯狂重连。状态同步重连成功后客户端需要向服务端同步当前状态如“我回来了我的玩家ID是XXX请把最新的游戏状态发给我”。服务端需要维护客户端的会话状态。5.3 广播、组播与单播策略服务端向客户端发送消息有三种基本模式广播Broadcast发给所有连接的客户端。适用于全局公告、全服事件。组播/房间Multicast/Room发给特定组内的客户端。这是多人游戏的核心需要服务端维护房间和玩家映射关系。单播Unicast发给特定的一个客户端。用于私聊、个人状态更新。在Fleck中实现这些模式的关键是管理好allClients这个连接列表。你可以为每个连接附加业务数据如玩家ID、房间号然后通过LINQ查询筛选出目标连接进行发送。// 假设连接对象上附加了自定义数据 public class ClientInfo { public IWebSocketConnection Connection { get; set; } public string PlayerId { get; set; } public string RoomId { get; set; } } static ListClientInfo allClientInfos new ListClientInfo(); // 广播给某个房间的所有人除发送者 static void SendToRoom(string roomId, string message, string excludePlayerId null) { var targets allClientInfos.Where(c c.RoomId roomId c.PlayerId ! excludePlayerId); foreach (var client in targets) { client.Connection.Send(message); } }6. 常见问题与调试技巧6.1 连接失败排查清单问题现象可能原因解决方案Unity报Unable to connect1. 服务端未启动。2. 防火墙阻止了端口。3. IP地址或端口错误。4. 服务端监听地址不是0.0.0.0。1. 检查服务端控制台是否成功启动。2. 在Windows防火墙或安全软件中添加入站规则允许该端口。3. 确认Unity中serverAddress与服务端WebSocketServer的地址完全一致。4. 服务端改用ws://0.0.0.0:端口。连接成功但立即断开1. 心跳机制过于激进服务端主动断开。2. 服务端或客户端代码中有未处理的异常导致连接关闭。1. 检查并调整心跳间隔和超时时间。2. 在服务端和客户端的OnError回调中打印详细日志。可以连接但收不到消息1. 消息前缀协议不一致。2. 发送和接收的消息格式文本/二进制不匹配。3. 网络延迟或丢包。1. 仔细核对客户端和服务端对消息前缀如 ‘T‘ ’J‘, 0x02的定义。2. 确保发送SendText对应接收OnMessage(string)发送Send(byte[])对应接收OnBinary或OnMessage(byte[])。3. 在稳定网络下测试并考虑加入消息确认和重传机制。6.2 性能问题与优化建议频繁GC垃圾回收导致卡顿在Unity Update中频繁创建新的字符串或字节数组用于发送消息会引发GC。解决方案是使用对象池或复用数组。对于固定格式的消息可以预分配内存。消息风暴如果每帧都发送玩家的位置比如60次/秒会对网络和服务端造成巨大压力。解决方案是状态同步采用差值同步只发送发生变化的状态。降低同步频率根据距离和重要性采用不同的同步频率如远处玩家10次/秒近处玩家30次/秒。客户端预测与服务器调和这是大型联机游戏的进阶话题可以大幅提升流畅性。服务端单线程瓶颈Fleck默认是单线程处理事件回调。如果逻辑复杂或连接数过多可能成为瓶颈。可以考虑将耗时的业务逻辑如数据库操作、复杂计算放入Task.Run中避免阻塞主事件循环。对于超大规模应用需要考虑分布式架构将连接分散到多个服务实例。6.3 调试工具推荐浏览器开发者工具Chrome/Firefox的Network面板可以监控WebSocket连接和消息非常适合调试WebGL版本的Unity应用。Wireshark网络封包分析工具可以抓取和分析最底层的WebSocket数据帧适合排查复杂的协议问题。简单的测试客户端用Python的websockets库或Node.js的ws库快速写一个脚本模拟客户端发送各种消息用于隔离测试服务端逻辑。Unity Editor Log和服务端控制台输出保持清晰的日志分级Info, Warning, Error是定位问题最快的方法。我个人在多个小到中型项目中使用这套方案的经验是它的起步非常快能让你在几个小时内就搭建起可用的实时通信框架。最大的坑往往不在通信本身而在业务逻辑的状态管理和网络异常处理上。例如玩家突然断线后他的游戏实体该如何处理其他玩家看到的是什么重连后如何恢复这些问题需要在设计之初就考虑清楚。另外对于真正的生产环境务必使用WSS并考虑将Fleck服务端以Windows服务或Linux systemd服务的形式运行以保证其稳定性和开机自启。