跳到主要内容
VibrantLink 动联无限
接入指南中文指南

PUN 2 的设置与连接:从 AppID 到房间与事件

从 AppID 到房间:PUN 2 的导入、PhotonServerSettings 字段、ConnectUsingSettings、回调、创建/加入房间、事件与测试。

SDK 用法、API 参考、代码示例、区域表与平台支持矩阵以光子官方文档为准;本站只维护中国区可用性、额度、价格与合同口径、上线合规和支持渠道。

阅读约 10 分钟更新于 2026 年 11 月 15 日光子原文
本页目录
  1. 01 · 适用范围
  2. 02 · 创建 Realtime AppID
  3. 03 · 导入 PUN 与打开配置
  4. 04 · PhotonServerSettings 逐项说明
  5. 05 · 连接与回调
  6. 06 · 创建、加入与匹配
  7. 07 · 事件、RPC 与状态同步
  8. 08 · 双客户端测试
  9. 09 · 自托管 Server 与 PUN 2 的差异

PUN 2 把 Realtime 的房间、事件与 RPC 封装成 Unity 友好的一套组件。即使你不打算在新项目里使用它,维护存量项目时也需要知道当前配置入口在哪里,以及哪些 PUN 1 的做法已经不再适用。

PUN 2 使用 Realtime AppID;Chat 与 Voice 需要额外 AppID。

PhotonServerSettings 是 ConnectUsingSettings 的主要配置源。

截至 2026-11,PUN 2 处于维护 / LTS;新项目优先评估 Fusion / Quantum。

除了“能连上”,连接、进房、事件与 RPC 也值得分别验证。

01适用范围

本页面向需要维护的 PUN 2 Unity 项目。PUN 1/Classic 的 CloudRegionCode、CloudRegionFlag、修改 NetworkingPeer.cs 等做法不属于 PUN 2 的当前配置路径,不应继续传播。

02创建 Realtime AppID

在 Photon Dashboard 创建 Realtime 应用。AppID 只对应这个产品;Chat、Voice 需要分别创建。中国区还需要先解锁,并建议中国构建使用独立 AppID。

03导入 PUN 与打开配置

在 Unity 导入 PUN 2 后,首次通常会弹出 PUN Wizard,可从 Window → Photon Unity Networking 再次打开。Wizard 会创建 PhotonServerSettings 资产。自托管场景可以跳过云端向导,直接编辑该资产。

04PhotonServerSettings 逐项说明

PhotonServerSettings 常用字段
字段作用注意
AppId RealtimeRealtime 应用标识不是 Chat/Voice AppID
App Version匹配隔离版本两端必须一致
Use Name Server使用 NameServer 引导云端开启;旧自托管 v4 才关闭
Fixed Region固定区域留空为 Best Region
Dev Region开发区域仅 Editor / Development Build
ServerNameServer 或自托管地址中国区填 ns.photonengine.cn
Port and Protocol端口与协议Cloud 端口 0,默认可靠 UDP
RPC ListRPC 名称索引不要手工破坏

05连接与回调

C# / 连接

verify against target SDK
// Official docs: https://doc.photonengine.com/pun/current/getting-started/initial-setup
// China differences: https://vibrantlink.com/resources/pun-china-region
// Quota & pricing: https://vibrantlink.com/pricing

public class RoomConnector : MonoBehaviourPunCallbacks {
    void Start() {
        PhotonNetwork.ConnectUsingSettings();
    }

    public override void OnConnectedToMaster() {
        PhotonNetwork.JoinOrCreateRoom(
            "room1",
            new RoomOptions { MaxPlayers = 4, IsVisible = true },
            TypedLobby.Default
        );
    }

    public override void OnJoinedRoom() {
        Debug.Log($"Joined: {PhotonNetwork.CurrentRoom.Name}");
    }
}

ConnectUsingSettings() 是异步的。继承 MonoBehaviourPunCallbacks 或实现 IConnectionCallbacks 后,把匹配、进房和 UI 状态迁移放到对应回调中。连接失败先检查 AppID 类型、AppVersion、区域与日志。

06创建、加入与匹配

  • JoinOrCreateRoom:房间存在则加入,否则创建,适合固定房名。
  • CreateRoom:要求房名未被占用;成功进入 OnJoinedRoom。
  • JoinRoom:房间必须存在、可见且未满。
  • JoinRandomRoom:按大厅与属性匹配空闲房间。
  • 失败分别进入 OnCreateRoomFailed、OnJoinRoomFailed、OnJoinRandomFailed。

房间可见性、最大人数和自定义属性会影响匹配结果。需要私有房间时,把 IsVisible 设为 false,并通过邀请或外部匹配传递房名。

07事件、RPC 与状态同步

事件用 PhotonNetwork.RaiseEvent 发送,事件码 1–199 可自定义;RPC 用 [PunRPC] 标记,通过 photonView.RPC 调用;需要持续同步的状态实现 IPunObservable.OnPhotonSerializeView,并挂在带 PhotonView 的 prefab 上。

C# / 事件与 RPC

verify against target SDK
PhotonNetwork.RaiseEvent(
    1,
    eventContent,
    new RaiseEventOptions { Receivers = ReceiverGroup.All },
    SendOptions.SendReliable
);

[PunRPC]
void OpenDoor(int doorId) {
    // 门状态更新
}

photonView.RPC("OpenDoor", RpcTarget.All, 1);

08双客户端测试

  1. 在 Editor 运行一个客户端,再启动一个独立构建。
  2. 两端使用同一 AppID、AppVersion 和区域。
  3. 验证 OnConnectedToMaster → OnJoinedRoom → 事件 / RPC。
  4. 检查断线、重连和房间属性恢复。
  5. 需要细节时临时启用 Support Logger,完成后恢复常规日志级别。

09自托管 Server 与 PUN 2 的差异

连接自托管 Photon Server 5 时,Server 字段应填客户端可达的地址;区域选择要与 Nameserver.json 的 region token 匹配;端口可填 0 让 SDK 自动选择。不要把 Photon Server v4 的 5055 端口、GpBinaryV16 或关闭 Name Server 等旧做法混入 v5。

Official sources

本文依据上述光子文档整理与翻译,仅供中文接入参考。若与光子英文文档、SDK 实际行为或双方合同不一致,以光子资料与合同为准。

旧地址 /punsetting/ 会永久跳转到本页,原有链接仍可访问。

Need help?

把文档里的步骤,落到你的项目里。

中国区 AppID、区域、许可与部署问题,可以带着项目背景直接询问。 我们不会索要账号密码。