1. 项目概述为什么选择Photon Server进行本地联机开发如果你正在用Unity做联机游戏尤其是像多人对战、房间匹配这类需要实时同步的功能那么服务器选型就是你绕不开的第一道坎。市面上有Unity Netcode、Mirror、PUN这些方案但很多团队特别是中小型项目或者想从零开始深入理解网络同步底层逻辑的开发者最终还是会考虑Photon Server。原因很简单它提供了一个介于“全托管云服务”和“从零手写Socket”之间的绝佳平衡点。你既不用操心物理服务器的运维又能获得对网络逻辑近乎完全的控制权最关键的是它支持你在自己的电脑上搭建一个本地开发环境这对于前期调试、逻辑验证和成本控制来说是无可替代的优势。我见过不少项目一开始为了图省事直接用第三方匹配服务到了中后期发现自定义的游戏逻辑比如复杂的技能判定、非对称玩法难以接入或者延迟、费用成了瓶颈再想迁移就非常痛苦。而Photon Server的本地部署让你在开发阶段就能把整套网络通信的“黑盒”变成“白盒”所有数据包怎么发、怎么收、服务器逻辑怎么跑都一清二楚。这对于培养团队的网络编程能力、后期性能优化和线上问题定位价值巨大。这次我就带你从零开始手把手搭建一套Photon Server的本地开发环境并完成一个最基础的Unity客户端连接示例。整个过程我会穿插我踩过的坑和总结的技巧目标是让你搭完就能跑通一个最简单的“Hello World”级联机demo。2. 环境准备与核心组件解析在动手之前我们得先搞清楚Photon Server这套体系里有哪些关键角色以及它们各自的作用。很多人一开始就被各种名词搞晕了我们先来理一理。2.1 Photon Server的核心架构与组件选择Photon Server本质上是一个用C#编写的高性能Socket服务器框架。我们下载的安装包其实是它的“运行时”和“开发套件”。它主要包含两部分Photon Socket Server这是核心的高性能通信层用C编写负责处理底层的TCP/UDP连接、数据包收发和线程调度。我们通常不直接对它编程。Photon Server SDK这是我们主要打交道的地方。它是一系列C#的类库和工具让我们能用C#来编写具体的游戏逻辑在Photon里称为“应用程序”或“App”。SDK里最重要的概念是“Peer”对等端和“Operation”操作客户端发来的任何请求都会被封装成一个Operation交给我们的C#逻辑代码来处理。对于本地开发我们需要从Photon官网下载Photon Server SDK。这里有个关键选择版本。Photon Server有“免费版”和“企业版”。对于本地开发、测试以及小规模并发比如小于100CCU的原型验证免费版完全足够。它只是限制了最大并发连接数和一些高级企业功能核心的编程接口和本地运行能力都是完整的。所以放心去官网注册一个账号下载免费的SDK就好。除了Photon Server本身你的开发机上还需要.NET FrameworkPhoton Server的SDK和它编译出来的服务端逻辑需要.NET Framework作为运行时。通常安装最新版本的.NET Framework 4.x即可。你可以在Windows的“启用或关闭Windows功能”里检查是否已安装。Unity这个不用说我们的客户端。建议使用一个稳定的LTS版本比如2021.3 LTS或2022.3 LTS避免最新版本可能存在的未知插件兼容性问题。一个代码编辑器服务端C#代码可以用Visual Studio 2019/2022社区版就够用。客户端的Unity C#脚本用Visual Studio或Rider都可以。2.2 安装与目录结构初探从官网下载的Photon Server SDK通常是一个压缩包解压到一个没有中文和空格的路径下比如D:\PhotonServer。解压后的目录结构很重要我们需要熟悉一下PhotonServer/ ├── deploy/ # 这是核心目录我们编写的服务器应用程序将部署在这里 │ ├── bin_Win64/ # 64位Windows的Photon核心运行文件 │ ├── bin_Win32/ # 32位版本一般不用 │ ├── lib/ # 依赖的动态链接库 │ └── log/ # 服务器运行时日志出问题时第一个要查的地方 ├── doc/ # 官方文档虽然有点旧但API参考有价值 ├── lib/ # SDK的库文件我们开发服务端应用时会引用 ├── src-server/ # 示例服务器应用程序的源代码最佳学习资料 ├── PhotonControl.exe # 服务器控制台图形界面 └── PhotonSocketServer.exe # 核心服务器进程通常通过PhotonControl启动deploy目录是我们工作的主战场。Photon Server启动时会加载deploy目录下的配置和应用程序。我们自研的游戏服务器逻辑最终编译成DLL也要放到deploy下某个特定的子目录里。src-server里的示例代码尤其是LoadBalancing和Chat示例是理解Photon编程模型的最佳起点强烈建议通读。注意安装路径千万不要包含中文或特殊字符这是很多“启动失败”错误的根源。同样后续Unity项目的路径也应遵循此原则。3. 服务器端配置与第一个应用程序环境准备好了我们现在来让Photon Server跑起来并创建我们的第一个服务端应用。这个过程有点像配置一个Web服务器比如IIS然后部署一个网站应用。3.1 基础配置与服务器启动首先我们需要配置Photon Server让它知道怎么运行。关键配置文件是deploy\PhotonServer.config。用文本编辑器打开它你会看到XML格式的配置。对于本地开发大部分默认设置都可以不动但需要关注两个地方Application路径配置文件里定义了Photon Server会加载哪些“应用程序”。默认可能已经有一些示例应用的配置。我们稍后需要在这里添加我们自己的应用。TCP/UDP端口Photon默认使用TCP端口4530和UDP端口5055。确保这些端口没有被你电脑上的其他程序如某些游戏、MySQL等占用。如果被占用可以在配置文件的WebSocket和UDPListener节点里修改Port属性。配置好后就可以启动服务器了。运行PhotonControl.exe你会看到一个管理界面。点击“Start”按钮。如果一切正常下方的日志区域会显示“Photon Socket Server started”之类的信息并且“Stop”按钮会变为可用。如果启动失败日志会给出错误信息最常见的是端口占用或配置文件语法错误。3.2 创建与部署自定义服务器应用现在我们来创建一个最简单的“Echo”服务器应用客户端发什么消息过来服务器就原样发回去。这能验证通信链路是否通畅。第一步在Visual Studio中创建类库项目。新建一个“类库(.NET Framework)”项目命名为MyGameServer。目标框架选择.NET Framework 4.x与Photon Server SDK要求的版本一致。然后需要添加对Photon Server SDK的引用。在项目引用中添加“浏览”找到你Photon Server SDK目录下的lib文件夹添加Photon.SocketServer.dll和PhotonHostRuntimeInterfaces.dll。这两个是最核心的库。第二步编写主应用程序类。在Photon中一个服务器应用由一个继承自ApplicationBase的类作为入口。新建一个类MyGameApplicationusing Photon.SocketServer; using PhotonHostRuntimeInterfaces; namespace MyGameServer { public class MyGameApplication : ApplicationBase { // 当一个新的客户端Peer连接时被调用 protected override PeerBase CreatePeer(InitRequest initRequest) { // 返回我们自定义的Peer对象来处理这个客户端的请求 return new MyGamePeer(initRequest); } // 服务器应用启动时被调用 protected override void Setup() { Log(MyGameServer 应用程序启动成功); } // 服务器应用停止时被调用 protected override void TearDown() { Log(MyGameServer 应用程序正在关闭...); } } }第三步编写对等端Peer类。Peer类负责处理单个客户端的全部请求。新建一个类MyGamePeerusing Photon.SocketServer; using PhotonHostRuntimeInterfaces; using System; namespace MyGameServer { public class MyGamePeer : PeerBase { public MyGamePeer(InitRequest initRequest) : base(initRequest) { } // 当客户端断开连接时被调用 protected override void OnDisconnect(DisconnectReason reasonCode, string reasonDetail) { Log($客户端 {ConnectionId} 断开连接。原因: {reasonDetail}); } // 最重要的方法处理客户端发来的操作请求 protected override void OnOperationRequest(OperationRequest operationRequest, SendParameters sendParameters) { // 根据操作码OperationCode来分发处理逻辑 switch (operationRequest.OperationCode) { case 1: // 假设操作码1是我们的Echo操作 HandleEchoOperation(operationRequest); break; default: // 未知操作码返回错误 var response new OperationResponse(operationRequest.OperationCode) { ReturnCode -1, DebugMessage $未知的操作码: {operationRequest.OperationCode} }; SendOperationResponse(response, sendParameters); break; } } private void HandleEchoOperation(OperationRequest request) { // 从请求参数中获取客户端发送的消息 if (request.Parameters.TryGetValue(1, out object messageObj) messageObj is string message) { Log($收到来自客户端 {ConnectionId} 的消息: {message}); // 构造响应 var response new OperationResponse(request.OperationCode) { Parameters new Dictionarybyte, object { { 1, $服务器回复: {message} } } }; // 发送响应回客户端 SendOperationResponse(response, new SendParameters()); } else { // 参数错误 var errorResponse new OperationResponse(request.OperationCode) { ReturnCode -2, DebugMessage 无效的请求参数 }; SendOperationResponse(errorResponse, new SendParameters()); } } private void Log(string msg) { // 使用Photon的日志接口日志会输出到PhotonControl或日志文件 Photon.SocketServer.Logging.LogManager.GetLogger(MyGame).Info(msg); } } }第四步编译与部署。在Visual Studio中编译项目生成MyGameServer.dll。然后在Photon Server的deploy目录下创建一个新的文件夹例如MyGameServer。将编译生成的MyGameServer.dll复制到这个新文件夹里。同时需要把项目依赖的Photon.SocketServer.dll和PhotonHostRuntimeInterfaces.dll如果它们不在GAC中也复制过来。更规范的做法是在Visual Studio中设置生成后事件自动将输出文件复制到deploy\MyGameServer\bin下。第五步修改配置文件注册我们的应用。回到deploy\PhotonServer.config找到Applications节点在里面添加我们的应用配置Application NameMyGame !-- 应用名称客户端连接时会用到 -- BaseDirectoryMyGameServer !-- 对应deploy下的子目录名 -- AssemblyMyGameServer !-- 我们DLL的名称不含后缀 -- TypeMyGameServer.MyGameApplication !-- 完整的类名包括命名空间 -- ForceAutoStarttrue !-- 是否随服务器自动启动 -- WatchFilesfalse !-- 开发时可设为true监视DLL变化热重载 -- /Application保存配置文件然后在PhotonControl中重启服务器。观察日志如果看到“MyGameServer 应用程序启动成功”的信息说明我们的服务器应用已经成功加载并运行了4. Unity客户端连接与通信实现服务器已经在跑了现在我们需要一个Unity客户端来连接它并发送Echo消息。Unity端我们使用Photon提供的客户端库Photon3Unity3D.dll通常包含在PUN等Asset Store资源包中也可以从Photon Server SDK的lib目录下找到对应版本。为了清晰我们创建一个全新的Unity项目。4.1 客户端库导入与连接配置在Unity项目中将Photon3Unity3D.dll放到Assets\Plugins文件夹下。如果没有Plugins文件夹就创建一个。然后我们创建一个简单的连接管理器脚本NetworkManager.cs挂载到一个空的GameObject上。首先建立连接using UnityEngine; using ExitGames.Client.Photon; using System.Collections.Generic; public class NetworkManager : MonoBehaviour, IPhotonPeerListener { private PhotonPeer peer; private string serverAddress 127.0.0.1:4530; // Photon Server默认地址和端口 private string applicationName MyGame; // 必须与服务器配置的Application Name一致 void Start() { // 创建PhotonPeer实例指定连接协议TCP/UDP这里是TCP peer new PhotonPeer(this, ConnectionProtocol.Tcp); // 开始连接 if (!peer.Connect(serverAddress, applicationName)) { Debug.LogError(连接初始化失败); } else { Debug.Log(正在连接服务器...); } } void Update() { // Photon Peer需要每帧调用Service()方法来处理网络消息 if (peer ! null) { peer.Service(); } } // 实现IPhotonPeerListener接口的方法 public void DebugReturn(DebugLevel level, string message) { Debug.Log($[Photon {level}]: {message}); } public void OnEvent(EventData eventData) { // 处理服务器主动推送的事件暂未使用 Debug.Log($收到事件Code: {eventData.Code}); } public void OnOperationResponse(OperationResponse operationResponse) { // 处理服务器对请求的响应 Debug.Log($收到操作响应OpCode: {operationResponse.OperationCode}, ReturnCode: {operationResponse.ReturnCode}); if (operationResponse.ReturnCode 0 operationResponse.Parameters.ContainsKey(1)) { string echoMessage (string)operationResponse.Parameters[1]; Debug.Log($服务器回复: {echoMessage}); } else { Debug.LogError($操作失败: {operationResponse.DebugMessage}); } } public void OnStatusChanged(StatusCode statusCode) { // 连接状态改变 switch (statusCode) { case StatusCode.Connect: Debug.Log(成功连接到服务器); // 连接成功后发送一个测试消息 SendEcho(Hello, Photon Server!); break; case StatusCode.Disconnect: Debug.Log(与服务器断开连接。); break; case StatusCode.Exception: case StatusCode.ExceptionOnConnect: Debug.LogError($连接异常: {statusCode}); break; } } // 发送Echo请求的方法 private void SendEcho(string message) { if (peer ! null peer.PeerState PeerStateValue.Connected) { Dictionarybyte, object parameters new Dictionarybyte, object(); parameters[1] message; // 参数键为1对应服务器端HandleEchoOperation中的键 bool result peer.OpCustom(1, parameters, true); // 操作码为1可靠发送 if (result) { Debug.Log($已发送消息: {message}); } else { Debug.LogError(发送消息失败); } } else { Debug.LogWarning(未连接到服务器无法发送消息。); } } void OnDestroy() { if (peer ! null peer.PeerState ! PeerStateValue.Disconnected) { peer.Disconnect(); } } }这段代码做了几件事在Start中创建PhotonPeer并尝试连接本地服务器。在Update中持续调用peer.Service()这是Photon网络层处理消息队列的关键必须每帧调用。实现了IPhotonPeerListener接口来接收回调。OnStatusChanged告诉我们连接成功或失败OnOperationResponse处理服务器对我们请求的回复。连接成功后调用SendEcho方法它使用peer.OpCustom发送一个操作码为1、携带消息参数的请求到服务器。在OnOperationResponse中我们解析服务器返回的Echo消息并打印出来。4.2 运行测试与基础调试现在确保你的Photon Server正在运行通过PhotonControl查看状态。然后在Unity编辑器中运行游戏。查看Unity的Console窗口你应该会看到类似以下的日志序列正在连接服务器... [Photon Info]: ... (一些连接日志) 成功连接到服务器 已发送消息: Hello, Photon Server! 收到操作响应OpCode: 1, ReturnCode: 0 服务器回复: 服务器回复: Hello, Photon Server!同时观察PhotonControl的日志窗口你应该能看到类似收到来自客户端 [某个ID] 的消息: Hello, Photon Server!的日志。如果两边日志都符合预期那么恭喜你一个最基础的、从Unity客户端到自建Photon Server的完整通信链路已经打通了这是万里长征的第一步但也是最坚实的一步。5. 本地开发环境下的高级配置与优化基础链路通了但在实际项目开发中我们还需要考虑更多。比如如何高效地迭代服务器逻辑如何调试如何模拟多客户端下面分享一些本地开发环境下的实战技巧。5.1 服务器应用的热重载与调试每次修改服务器C#代码后都要重新编译、复制DLL、重启Photon Server这太麻烦了。有两个技巧可以极大提升效率技巧一配置WatchFilestrue。在PhotonServer.config中你的应用配置里将WatchFiles属性设为true。这样Photon Server会监视你应用目录下DLL文件的变化。当你用Visual Studio重新编译并覆盖DLL后Photon Server会自动卸载旧应用并加载新版本无需手动重启整个服务器。这在开发初期逻辑频繁变动时非常有用。但注意它不能处理所有类型的更改比如静态构造函数或某些类型的卸载可能有问题如果遇到加载失败还是需要重启服务器。技巧二使用Visual Studio附加进程进行调试。这是最强大的调试手段。首先在Visual Studio中打开你的服务器应用项目在代码里设好断点。然后在PhotonControl中启动服务器。接着在Visual Studio的菜单栏选择“调试” - “附加到进程”。在进程列表中找到PhotonSocketServer.exe注意不是PhotonControl.exe选中它点击“附加”。现在当Unity客户端发送请求触发你的服务器代码时Visual Studio就会在断点处停下来你可以查看所有变量、调用栈就像调试普通程序一样。这是定位复杂逻辑错误的终极武器。5.2 使用负载均衡LoadBalancing示例进行扩展我们刚才写的Echo服务器是一个“单应用”架构。但在真实的游戏中我们可能有大厅、房间、聊天等不同功能模块。Photon Server通过“负载均衡”机制来管理多个应用。src-server目录下的LoadBalancing示例就是一个完整的、带大厅和房间管理的实现它是学习Photon Server高级用法的宝库。对于本地开发即使你只有一个物理服务器也可以运行LoadBalancing示例。它包含了Master Server负责客户端连接、认证、分配应用服务器这里是Game Server。Game Server负责具体的游戏房间逻辑。在本地你可以将Master和Game Server配置在同一台机器的不同端口上。学习这个示例的代码你会理解如何使用Peer.CurrentOperationHandler来更优雅地分发操作处理。管理房间Room和玩家Actor。使用事件Event进行服务器到客户端的主动推送。实现自定义的序列化Serialization来高效传输游戏状态。我建议的做法是不要从头再造轮子。以LoadBalancing示例为起点复制它的项目结构然后逐步替换或增加你自己的游戏逻辑。这样能避免很多底层架构上的坑。5.3 多客户端测试与性能初步观察在Unity编辑器中你可以通过复制多个游戏窗口通过命令行参数-popupwindow启动多个编辑器实例来模拟多个客户端。但更高效的方法是写一个简单的“压力测试”客户端脚本在一个Unity实例中创建多个PhotonPeer来模拟大量用户连接和操作。对于本地性能观察PhotonControl界面本身提供了一些简单的连接数、流量统计。更详细的数据可以查看deploy\log目录下的日志文件里面记录了每个操作的耗时等信息。在开发阶段要特别关注OnOperationRequest方法中的逻辑是否高效避免阻塞操作因为Photon Server默认使用线程池来处理请求一个慢操作会影响其他客户端的响应。6. 常见问题排查与避坑指南搭建和开发过程中你肯定会遇到各种问题。这里我整理了一份最常见问题的排查清单希望能帮你快速定位。6.1 连接与配置类问题问题现象可能原因排查步骤与解决方案Unity客户端连接失败状态码StatusCode.ExceptionOnConnect1. 服务器未启动。2. IP地址或端口错误。3. 防火墙阻止了连接。4. 服务器配置的Application Name与客户端连接时使用的名称不匹配。1. 检查PhotonControl是否显示“Running”。2. 确认Unity代码中的serverAddress如127.0.0.1:4530和applicationName。3. 临时关闭Windows防火墙或添加入站规则。4. 核对PhotonServer.config中Application Name...与客户端代码中的字符串是否完全一致大小写敏感。服务器启动失败日志显示“Failed to load application...”1. 配置文件XML语法错误。2. 应用程序DLL路径或名称错误。3. 依赖的DLL如Photon.SocketServer.dll缺失或版本不匹配。4. 自定义应用代码编译错误或入口类找不到。1. 用XML验证工具检查PhotonServer.config。2. 确认BaseDirectory和Assembly属性指向正确的文件夹和DLL文件名不含.dll。3. 确保deploy\YourApp\目录下有所有必需的DLL。4. 检查Visual Studio编译是否成功以及Type属性中的命名空间和类名是否正确。客户端能连接但发送请求后收不到响应1. 客户端操作码与服务器处理的操作码不匹配。2. 服务器端的OnOperationRequest方法没有处理该操作码或处理逻辑有异常未捕获。3. 客户端没有持续调用peer.Service()。1. 在客户端OpCustom和服务器switch语句中打印或调试确认操作码值。2. 在服务器OnOperationRequest方法开始处加日志确认请求是否到达。用try-catch包裹处理逻辑。3. 确保Unity的Update()中调用了peer.Service()。服务器日志中出现大量错误或警告1. 客户端异常断开服务器资源未正确释放。2. 序列化/反序列化错误传输了不支持的数据类型。3. 线程池或资源耗尽。1. 确保在Peer的OnDisconnect或OnOperationRequest中妥善处理异常和资源清理。2. 确保通过OperationRequest.Parameters传递的数据类型是Photon支持的基础类型如int, string, float, Hashtable, Dictionary等或实现了CustomType接口的自定义类型。3. 对于本地开发通常不会遇到。如果出现检查是否有死循环或阻塞调用。6.2 开发与调试类问题断点不生效附加调试时确保你附加的是PhotonSocketServer.exe进程并且你编译的DLL版本与服务器加载的完全一致修改代码后要重新编译并部署。有时需要禁用“仅我的代码”调试选项。热重载后服务器行为异常WatchFiles热重载并不完美。如果遇到奇怪的问题首先尝试在PhotonControl中完全停止再启动服务器应用或者重启整个Photon Server。Unity端NullReferenceException最常见的原因是peer对象为null或在断开连接后继续使用。在任何调用peer的方法之前都要检查peer ! null peer.PeerState PeerStateValue.Connected。数据同步不同步在简单的Echo测试中不会出现但在真正的游戏状态同步中这是核心难题。务必仔细设计你的操作Operation和事件Event协议。谁服务器在什么时候、以什么频率、向谁单个玩家、房间内所有玩家、其他玩家发送什么数据这个逻辑必须清晰。Photon不提供内置的游戏状态权威计算这需要你自己在服务器端实现。6.3 一个关键的避坑点协议与序列化Photon默认的序列化方式对C#的基础类型和某些集合支持很好但如果你需要传输一个自定义的类对象比如一个PlayerInfo结构体你需要为其注册自定义类型。这通常在客户端和服务器端的初始化代码中完成// 在客户端和服务器端都需要执行的注册代码 public class PlayerInfo { public string Name { get; set; } public int Score { get; set; } } // 注册自定义类型 ExitGames.Client.Photon.Protocol.TryRegisterType( typeof(PlayerInfo), (byte)P, // 分配一个唯一的字节码 PlayerInfoSerializer.Serialize, PlayerInfoSerializer.Deserialize );忘记注册自定义类型或者客户端与服务器注册的字节码、序列化方法不一致会导致反序列化失败数据丢失。在本地开发阶段最好将这部分注册代码放在一个共享的DLL中供客户端和服务器共同引用确保一致性。搭建本地Photon Server环境的过程就像在给自己搭建一个私密的网络实验室。一开始可能会被配置和概念困扰但一旦跑通你对网络游戏的理解会深入一个层次。它能让你在早期就以极低的成本验证网络玩法在出现线上问题时本地复现和调试的能力更是无价。从今天这个简单的Echo服务器开始尝试去修改它增加一个简单的聊天功能或者做一个两人同步移动的demo每一步的实践都会带来新的收获。当你真正需要将服务器部署到Linux云主机上时你会发现90%的坑已经在本地踩过并解决了。