1. 项目概述：为什么选择Netcode for GameObjects做局域网同步？

如果你正在开发一款需要多人联机的游戏，比如一个宿舍开黑的派对游戏，或者一个公司内部培训用的模拟器，那么“局域网同步”这个需求大概率会找上门。Unity官方推出的Netcode for GameObjects（简称NGO）框架，就是来解决这个问题的。它不是一个简单的网络库，而是一个为Unity量身定制的、基于ECS思想（虽然它本身不是纯ECS）的高层网络框架。简单说，它让你能用处理单机游戏对象的思维，去处理网络游戏对象，大大降低了入门门槛。

为什么是NGO，而不是Mirror、Photon或者自己写Socket？对于局域网项目，尤其是中小型、开发周期紧张的团队项目，NGO的优势非常明显。首先，它是官方的，与Unity引擎的集成度最高，生命周期有保障，不用担心第三方库突然停止维护。其次，它抽象得很好，你不需要关心数据包怎么组、UDP还是TCP、序列化细节，你只需要关心“这个对象在网络上的状态是什么”。最后，它的“网络对象”（NetworkObject）和“网络变量”（NetworkVariable）概念非常直观，对于Unity开发者来说几乎没有额外的学习成本。

这个指南的核心，就是带你绕过官方文档里那些“大而全”的云端部署和Relay服务，直击局域网开发的核心痛点。我们会从零开始，搭建一个高效的、可扩展的局域网同步原型，涵盖从对象生成、状态同步到玩家输入处理的全流程，并分享那些官方文档里不会写的“坑”和优化技巧。

2. 核心概念与架构设计拆解

在动手写代码之前，必须理解NGO在局域网环境下的几个核心工作模式和数据流，这决定了你整个项目的架构。

2.1 主机（Host）与客户端（Client）模式

在局域网同步中，最经典的模式就是“主机-客户端”架构。NGO天然支持这种模式，并且通常由一个玩家同时担任“服务器”（Server）和“客户端”（Client），这就是“Host”模式。其他玩家则作为纯“客户端”（Client）加入。

• Host（主机）：这是局域网游戏的核心。它运行着游戏的“权威”逻辑。所有游戏规则判定、物理计算（如果需要服务器验证）、关键状态更新都发生在这里。同时，Host本身也是一个玩家，能看到自己的角色并操作。
• Client（客户端）：连接到Host的机器。它接收来自Host的权威状态更新，并将本地玩家的输入发送给Host。客户端也会进行预测和插值等渲染优化，但最终状态以Host为准。

为什么选择Host模式而不是纯服务器模式？对于大部分小规模局域网游戏（2-8人），让一个玩家的机器同时作为服务器是最高效、最简单的方案。它省去了部署独立服务器的成本，网络延迟也最低（对于Host自己）。NGO的NetworkManager组件可以很方便地一键启动Host。

2.2 网络对象（NetworkObject）与网络变量（NetworkVariable）

这是NGO同步的基石。

• NetworkObject：任何需要在网络上存在的GameObject，都必须挂载这个组件。它给GameObject一个网络身份（NetworkId）。你可以把它理解为一个对象的“网络护照”，没有它，这个对象就无法在多个玩家间被识别和同步。
• NetworkVariable：这是同步数据的主要工具。它是一个泛型容器（如NetworkVariable<int>,NetworkVariable<Vector3>），其值的变化会自动通过网络同步给所有客户端。它支持多种同步方式：
  • NetworkVariableReadPermission.Everyone：所有人可读可写（需在服务器端修改）。
  • NetworkVariableReadPermission.Owner：只有对象所有者和服务器可写，其他人只读。
  • NetworkVariableReadPermission.Custom：自定义。

关键设计原则：尽可能使用NetworkVariable来同步状态，而不是用RPC（远程过程调用）来频繁发送数据。RPC更适合离散的事件（如“开枪”、“跳跃”），而连续的状态（如位置、血量、分数）用NetworkVariable更高效，因为NGO内部会对其进行优化和增量更新。

2.3 RPC与客户端预测

虽然NetworkVariable很好，但玩家的输入处理需要即时反馈，不能等到服务器确认才响应，否则操作会感觉极其迟钝。这就引入了RPC和客户端预测。

• RPC（远程过程调用）：允许你在一个客户端上调用一个方法，并在服务器或其他客户端上执行。分为：
  • [ServerRpc]：从客户端调用，在服务器上执行。用于发送玩家的指令到权威端。
  • [ClientRpc]：从服务器调用，在所有客户端或指定客户端上执行。用于广播服务器确认的结果或事件。
• 客户端预测：为了流畅性，客户端在发送[ServerRpc]（如“移动指令”）后，不等服务器回包，立即在本地模拟这个指令的结果（如先移动角色）。当服务器权威状态同步回来后，如果和本地预测有出入，再进行“纠正”或“调和”。这是实现流畅多人体验的关键，也是难点所在。

我们的架构设计思路是：用NetworkVariable同步权威的、不频繁变化的状态；用[ServerRpc]上传玩家输入；在客户端对输入进行立即响应（预测）；用[ClientRpc]或NetworkVariable同步服务器验证后的最终结果。

3. 环境准备与基础项目搭建

3.1 安装与初始配置

首先，确保你使用的是Unity 2021.3 LTS或更高版本，这是NGO稳定运行的基础。通过Package Manager安装Netcode for GameObjects。安装后，你的项目中会出现相关的程序集和菜单。

第一步，创建一个空的GameObject，重命名为“NetworkManager”，并为其添加NetworkManager组件。这是整个网络系统的控制中心。同时，为了方便，把Unity提供的UnityTransport组件也挂上去，这是NGO默认的网络传输层。

注意：NetworkManager是一个单例管理器，通常一个场景中只有一个。它会自动处理连接、断开、场景同步和对象生成等全局网络事件。

接下来，配置UnityTransport。对于纯局域网开发，我们主要关心一个参数：Connection Data中的Address和Port。

• Address：对于服务器/Host，如果你想允许同一局域网内任何IP的机器连接，可以设置为0.0.0.0（表示监听所有网络接口）。对于客户端，这里要填写Host机器的局域网IP地址（如192.168.1.100）。
• Port：设置一个未被占用的端口号，比如7777。Host和所有Client必须使用相同的端口号。

3.2 创建第一个可同步的玩家预制体

1. 制作预制体：创建一个胶囊体（Capsule）作为玩家角色，重命名为“PlayerPrefab”。
2. 添加NetworkObject：为这个预制体添加NetworkObject组件。这是必须的。
3. 添加网络变换组件：添加NetworkTransform组件。这个组件会自动同步GameObject的Position、Rotation和Scale。在Inspector中，你可以选择同步哪些（通常只同步Position和Rotation），以及同步的频率（NetworkTickRate影响的是网络更新帧率，不是渲染帧率）。
4. 制作玩家移动脚本：创建一个名为PlayerMovement的脚本。这个脚本需要继承NetworkBehaviour而不是MonoBehaviour。只有NetworkBehaviour才能使用NGO的网络功能。

using Unity.Netcode; using UnityEngine; public class PlayerMovement : NetworkBehaviour { public float moveSpeed = 5f; private Vector3 moveInput; void Update() { // 只有本地玩家控制的角色才处理输入 if (!IsOwner) return; float h = Input.GetAxis("Horizontal"); float v = Input.GetAxis("Vertical"); moveInput = new Vector3(h, 0, v).normalized; } void FixedUpdate() { if (!IsOwner) return; if (moveInput.magnitude > 0.1f) { // 在本地立即移动（预测） transform.position += moveInput * moveSpeed * Time.fixedDeltaTime; // 同时将移动指令发送给服务器 MoveServerRpc(moveInput); } } [ServerRpc] private void MoveServerRpc(Vector3 direction) { // 服务器接收到指令，进行权威移动计算 // 这里可以做作弊检测、规则校验等 transform.position += direction * moveSpeed * Time.fixedDeltaTime; // 注意：服务器端移动后，NetworkTransform会自动将新位置同步给所有客户端 } }

5. 配置NetworkManager：将制作好的“PlayerPrefab”拖拽到NetworkManager组件中的Player Prefab字段里。这样，当玩家连接时，NGO会自动为他在所有机器上生成这个预制体。

3.3 启动Host与连接Client

创建两个简单的UI按钮，分别用于“启动主机”和“连接客户端”。

using Unity.Netcode; using UnityEngine; using UnityEngine.UI; public class SimpleNetworkHUD : MonoBehaviour { public InputField ipInputField; // 输入Host IP的UI public NetworkManager networkManager; void Start() { if (networkManager == null) networkManager = NetworkManager.Singleton; } public void StartHost() { networkManager.StartHost(); Debug.Log("Host started!"); } public void StartClient() { if (string.IsNullOrEmpty(ipInputField.text)) { Debug.LogError("Please enter host IP!"); return; } // 获取UnityTransport并设置连接地址 var transport = networkManager.GetComponent<UnityTransport>(); if (transport != null) { transport.ConnectionData.Address = ipInputField.text; } networkManager.StartClient(); Debug.Log("Client connecting to: " + ipInputField.text); } }

至此，一个最基础的局域网同步框架就搭好了。在一台机器上点击“启动主机”，在另一台同局域网的机器上输入主机IP点击“连接客户端”，你应该能看到两个胶囊体出现在同一个场景中，并且各自可以移动，对方的移动也能被看到。

4. 核心同步机制深度解析与实现

基础框架跑通只是第一步。要做出体验良好的游戏，必须深入理解并正确实现以下几个核心机制。

4.1 状态同步：NetworkVariable的高级用法

简单的NetworkVariable<T>对于基础类型（int, float, bool）和Unity内置类型（Vector3, Quaternion）开箱即用。但同步自定义结构或类，需要实现INetworkSerializable接口。

示例：同步玩家状态（血量、弹药、装备）

using Unity.Netcode; // 自定义一个可序列化的玩家状态结构 public struct PlayerState : INetworkSerializable { public int CurrentHealth; public int CurrentAmmo; public bool HasKey; public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter { // 必须按相同的顺序序列化和反序列化 serializer.SerializeValue(ref CurrentHealth); serializer.SerializeValue(ref CurrentAmmo); serializer.SerializeValue(ref HasKey); } } public class AdvancedPlayer : NetworkBehaviour { // 使用自定义结构体的NetworkVariable private NetworkVariable<PlayerState> netState = new NetworkVariable<PlayerState>( new PlayerState { CurrentHealth = 100, CurrentAmmo = 30, HasKey = false }, NetworkVariableReadPermission.Everyone, // 所有人可读 NetworkVariableWritePermission.Server // 只有服务器可写，确保权威性 ); void OnEnable() { // 订阅状态变化事件 netState.OnValueChanged += OnStateChanged; } void OnDisable() { netState.OnValueChanged -= OnStateChanged; } private void OnStateChanged(PlayerState oldState, PlayerState newState) { // 当netState的值在网络上发生变化时，这个回调会在所有客户端触发 Debug.Log($"Health changed from {oldState.CurrentHealth} to {newState.CurrentHealth}"); UpdateUI(newState); // 更新本地UI } // 一个在服务器上修改状态的方法 public void TakeDamage(int damage) { if (!IsServer) return; // 确保只在服务器执行 var newState = netState.Value; newState.CurrentHealth -= damage; newState.CurrentHealth = Mathf.Max(0, newState.CurrentHealth); netState.Value = newState; // 赋值会自动触发同步 } }

关键点：NetworkVariable的写入权限（WritePermission）通常设为Server，这是保证游戏状态权威性和防作弊的基础。所有状态修改都应由服务器发起或确认。

4.2 输入处理与客户端预测实践

上面PlayerMovement的例子是最简单的预测：客户端直接移动。但存在“回滚”问题：如果服务器因为延迟或规则拒绝了这个移动，客户端就需要被拉回，体验很糟糕。更完善的预测需要状态缓冲和调和。

实现一个带缓冲和服务器校正的移动预测：

using Unity.Netcode; using UnityEngine; public class PredictedPlayerMovement : NetworkBehaviour { public float moveSpeed = 5f; private NetworkVariable<Vector3> serverPosition = new NetworkVariable<Vector3>(); // 服务器权威位置 private Queue<Vector3> inputBuffer = new Queue<Vector3>(); // 输入缓冲队列 private float bufferTime = 0.1f; // 缓冲时间 void Update() { if (!IsOwner) return; float h = Input.GetAxis("Horizontal"); float v = Input.GetAxis("Vertical"); Vector3 input = new Vector3(h, 0, v).normalized; if (input.magnitude > 0.1f) { // 1. 本地预测移动 transform.position += input * moveSpeed * Time.deltaTime; // 2. 将输入和时间戳存入缓冲 inputBuffer.Enqueue(input); // 3. 发送给服务器 MoveInputServerRpc(input); } // 非所有者，根据服务器位置进行插值（平滑） if (!IsOwner) { transform.position = Vector3.Lerp(transform.position, serverPosition.Value, Time.deltaTime * 10f); } } [ServerRpc] private void MoveInputServerRpc(Vector3 direction) { // 服务器模拟移动 transform.position += direction * moveSpeed * Time.deltaTime; // 将权威位置同步下去 serverPosition.Value = transform.position; } // 当收到服务器权威位置时（OnValueChanged） private void OnServerPositionChanged(Vector3 oldPos, Vector3 newPos) { if (!IsOwner) return; // 服务器位置更新了 // 将本地位置瞬间纠正到服务器位置（或一个平滑过渡的位置） transform.position = newPos; // 关键：用缓冲的输入，从新的服务器位置开始，重新模拟（重演）从那个时间点到现在的所有输入 // 这是一个简化的描述，完整实现需要记录输入时间戳，并做更复杂的时间重演。 // 这里清空缓冲，意味着我们接受了服务器的纠正，并基于新位置重新开始预测。 inputBuffer.Clear(); } }

实操心得：完整的客户端预测（如快照插值、状态调和）是网络编程中最复杂的部分之一。对于大部分非竞技类局域网游戏，如果延迟在50ms以内，可以适当简化。一个实用的折中方案是：对非关键性、视觉影响大的动作（如移动）做轻量预测（立即响应+平滑插值），对关键性动作（如射击命中）完全交由服务器裁决，用RPC播放效果。不要试图在第一个项目中就实现完美的预测，先让功能跑起来，再根据体验优化。

4.3 对象生成与所有权管理

在多人游戏中，生成子弹、道具、特效等动态对象非常常见。NGO提供了NetworkObject.Spawn方法，但必须注意生成权限。

• 服务器生成：任何网络对象，都必须由服务器（或Host）生成。客户端不能直接Instantiate一个带NetworkObject的预制体。
• 生成参数：Spawn方法可以传入一个bool参数，决定是否随场景同步。通常动态生成的对象（子弹）传false，场景中已放置好的静态网络对象传true。
• 所有权（Ownership）：每个NetworkObject都有一个所有者。默认生成者是所有者。所有权可以转移。所有者对该对象有特殊的权限，比如可以调用[ServerRpc]（需要RequireOwnership属性），服务器也会将某些更新优先发送给所有者。

示例：玩家发射子弹

public class PlayerShoot : NetworkBehaviour { public GameObject bulletPrefab; // 必须是带有NetworkObject的预制体 public Transform firePoint; void Update() { if (!IsOwner) return; if (Input.GetButtonDown("Fire1")) { RequestShootServerRpc(); } } [ServerRpc] private void RequestShootServerRpc() { // 只在服务器上执行生成逻辑 GameObject bulletGo = Instantiate(bulletPrefab, firePoint.position, firePoint.rotation); NetworkObject bulletNetworkObject = bulletGo.GetComponent<NetworkObject>(); bulletNetworkObject.Spawn(); // 生成并同步到所有客户端 // 可以将子弹的所有权转移给发射的玩家，方便后续处理（如伤害计算） // bulletNetworkObject.ChangeOwnership(NetworkObject.OwnerClientId); } }

5. 性能优化与调试技巧实录

局域网环境虽然延迟低，但带宽和性能并非无限。不当的使用依然会导致卡顿和不同步。

5.1 网络带宽优化策略

1. 降低同步频率：不是所有数据都需要每帧同步。在NetworkTransform和自定义的NetworkVariable更新中，可以通过降低NetworkTickRate（在NetworkManager中设置全局的网络更新率）或使用更低的发送频率来减少流量。对于变化缓慢的数据（如血量），可以手动控制更新时机。
2. 精简同步数据：
   • 使用Half或压缩格式：对于位置、旋转，如果精度要求不高，可以考虑在自定义序列化时使用Half类型或压缩算法。
   • 避免同步不变的数据：如果一个状态初始化后不再改变，用RPC初始化而不是NetworkVariable。
   • 使用NetworkVariable的OnValueChanged事件，而不是在Update中不断读取和比较。
3. 区分重要与非重要更新：NGO的RPC有Delivery参数。对于关键事件（如命中、死亡），使用Reliable（可靠传输）；对于非关键、高频事件（如脚步声、粒子效果位置），可以使用Unreliable（不可靠传输）以节省带宽和CPU开销。

5.2 常见问题与排查清单

在开发过程中，你一定会遇到各种同步问题。下面是一个快速排查清单：

5.3 调试工具与日志

1. NetworkManager HUD：NGO包内自带一个NetworkManagerHUD组件，勾选后运行游戏会在屏幕左上角显示简单的GUI，可以快速启动Host/Client/Server，非常方便调试。
2. 自定义网络日志：在NetworkManager的配置中，可以设置日志级别（LogLevel）。开发时设为Developer或Normal，可以查看详细的连接、RPC、生成日志。
3. 在代码中区分角色：善用IsServer,IsClient,IsOwner,IsLocalPlayer等属性，在调试时输出不同的日志颜色或前缀，能快速定位逻辑执行在哪个端。

void DebugLog(string message) { string prefix = ""; if (IsServer) prefix += "[S]"; if (IsClient) prefix += "[C]"; if (IsOwner) prefix += "[O]"; if (IsLocalPlayer) prefix += "[L]"; Debug.Log($"{prefix}: {message}"); }

6. 进阶话题：扩展性与架构思考

当你的原型验证通过，准备开发一个更完整的游戏时，需要考虑以下扩展性问题。

6.1 场景切换与网络场景管理

NGO支持同步加载场景。在NetworkManager中勾选Enable Scene Management。当服务器调用NetworkManager.SceneManager.LoadScene时，所有客户端会自动加载对应的场景。你需要确保每个场景中的网络对象都正确配置，并且场景在Build Settings中。

注意事项：场景切换时，DontDestroyOnLoad的对象如果带有NetworkObject，需要特殊处理。通常建议在切换场景时，由服务器统一管理重要网络对象的销毁和重新生成。

6.2 创建自定义网络消息

当NetworkVariable和RPC不能满足需求时（例如需要广播一个非常规结构的数据，或者想实现更底层的通信），可以使用自定义消息（Custom Messaging）。

using Unity.Netcode; using Unity.Collections; public class CustomMessageExample : NetworkBehaviour { private void SendCustomMessage(string text) { if (!IsServer) return; var writer = new FastBufferWriter(1024, Allocator.Temp); // 写入数据 writer.WriteValueSafe(text); // 发送给所有客户端（或指定客户端） NetworkManager.Singleton.CustomMessagingManager.SendUnnamedMessageToAll(writer); } // 需要注册接收器 void Start() { NetworkManager.Singleton.CustomMessagingManager.OnUnnamedMessage += ReceiveMessage; } void OnDestroy() { if (NetworkManager.Singleton != null) NetworkManager.Singleton.CustomMessagingManager.OnUnnamedMessage -= ReceiveMessage; } private void ReceiveMessage(ulong senderClientId, FastBufferReader reader) { reader.ReadValueSafe(out string receivedText); Debug.Log($"Received from {senderClientId}: {receivedText}"); } }

使用建议：自定义消息更灵活，但也更底层，需要自己处理序列化和反序列化。除非有明确需求（如同步大量自定义二进制数据），否则优先使用NetworkVariable和RPC。

6.3 断线重连与状态恢复

局域网游戏也可能出现网络波动或玩家暂时离开。基础的断线处理由NGO自动完成（客户端断开连接，其拥有的对象会被销毁）。但实现重连并恢复状态（如重连后回到游戏，看到之前的场景和角色）是一个高级特性。

简化思路：

1. 服务器维护一份所有持久化网络对象（如玩家、重要道具）的状态快照。
2. 当新客户端连接或旧客户端重连时，服务器首先加载基础场景。
3. 然后，服务器遍历快照，为这个客户端重新生成（Spawn）这些对象，并设置好正确的NetworkVariable状态。
4. 这需要你自定义连接处理流程，并可能用到NetworkSceneManager和对象池技术。

实现一个健壮的重连系统比较复杂，建议在项目后期，核心玩法稳定后再考虑添加。

从搭建第一个同步的玩家胶囊体，到处理复杂的预测和状态同步，再到优化和调试，利用Netcode for GameObjects进行局域网同步开发是一个从“能用”到“好用”的持续迭代过程。最关键的是理解“服务器权威”这一核心思想，并在此基础上，利用NGO提供的抽象，在保证逻辑正确的前提下，尽可能为本地玩家提供流畅的预测反馈。不要被一开始的网络延迟和不同步吓倒，大部分问题都有成熟的模式和解决方案。先从一个小功能跑通整个数据流，然后逐步丰富你的游戏世界，这个过程本身就像在搭建一个多人协作的乐高城堡，充满了挑战和乐趣。