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

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

- Canonical: https://vibrantlink.com/resources/pun-setup-and-connection
- Markdown: https://vibrantlink.com/resources/pun-setup-and-connection.md
- 分类：接入指南
- 更新：2026-11-15
- 旧地址：https://vibrantlink.com/punsetting/

## 关键要点

- PUN 2 使用 Realtime AppID；Chat 与 Voice 需要额外 AppID。
- PhotonServerSettings 是 ConnectUsingSettings 的主要配置源。
- 截至 2026-11，PUN 2 处于维护 / LTS；新项目优先评估 Fusion / Quantum。
- 除了“能连上”，连接、进房、事件与 RPC 也值得分别验证。

## 1. 适用范围

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

## 2. 创建 Realtime AppID

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

## 3. 导入 PUN 与打开配置

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

## 4. PhotonServerSettings 逐项说明

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

## 5. 连接与回调

**C# / 连接**
```
// 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、区域与日志。

## 6. 创建、加入与匹配

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

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

## 7. 事件、RPC 与状态同步

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

**C# / 事件与 RPC**
```
PhotonNetwork.RaiseEvent(
    1,
    eventContent,
    new RaiseEventOptions { Receivers = ReceiverGroup.All },
    SendOptions.SendReliable
);

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

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

## 8. 双客户端测试

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

## 9. 自托管 Server 与 PUN 2 的差异

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

## 参考来源

- PUN 2 初始设置: https://doc.photonengine.com/pun/current/getting-started/initial-setup
- PUN 2 介绍: https://doc.photonengine.com/pun/current/getting-started/pun-intro
- PUN 2 Regions: https://doc.photonengine.com/pun/current/connection-and-authentication/regions
- PUN 2 API: https://doc-api.photonengine.com/en/pun/v2/index.html

本页为中文接入参考，依据上述光子公开文档整理；具体 SDK、控制台和商业条款以实际使用的 Photon 版本、光子协议和订单为准。
