# 5 分钟接入 Photon Cloud：AppID、区域、房间与事件

用最短路径接入 Photon Cloud：创建 Realtime AppID、选择区域、连接 NameServer、创建或加入房间并发送事件，附中国区解锁与注意事项。

- Canonical: https://vibrantlink.com/resources/photon-cloud-in-5-minutes
- Markdown: https://vibrantlink.com/resources/photon-cloud-in-5-minutes.md
- 分类：快速开始
- 更新：2026-11-15
- 旧地址：https://vibrantlink.com/5minsphotoncloud/

## 关键要点

- 截至 2026-11，Cloud 是托管服务；Realtime 是房间与事件基础层；PUN 2 是 Unity 封装，处于维护 / LTS 模式。
- AppID 是 Photon 产品级标识，Chat、Voice 需要各自 AppID；中国区 AppID 还要单独解锁。
- 客户端必须持续调用 Service() 处理网络消息，ConnectUsingSettings() 返回并不等于连接完成。
- 中国区建议独立构建；独立 AppID 是光子建议而非所有场景的技术强制。

## 1. 先分清 Cloud、Realtime 与 PUN

Photon Cloud 是托管运行时，Realtime 是房间、匹配、事件与认证的底层 API。PUN 2 则是 Unity 侧的房间制封装，底层使用 Realtime。当前 PUN 2 已进入 maintenance / LTS 模式：存量项目继续支持，但新项目应评估 Fusion 或 Quantum。

下面的最短路径根据 Realtime 5 与 PUN 2 的当前光子文档整理。不同 SDK 版本的类名可能略有变化，发布前请以你实际使用的版本为准。

## 2. 创建正确的 AppID

1. 登录 Photon Dashboard，创建一个 Realtime 类型的应用。
2. AppID 是 GUID，只能用于对应产品；Chat、Voice 和 Realtime 不要混用。
3. 如果面向国内玩家，请通过 Photon 控制台或联系渠道为这个 AppID 申请中国区解锁。
4. 不要公开贴出完整 AppID；联系支持时通常只需前 8 位。

> **中国区不是只改一个区域字符串**
>
> 中国区 AppID 需要单独解锁，光子要求为国内环境制作单独构建，并建议使用独立 AppID。客户端还必须使用本地 NameServer ns.photonengine.cn。

## 3. 选择区域：Best Region、固定区域与白名单

不指定区域时，客户端默认使用 Best Region：NameServer 返回区域列表，客户端 ping 后选择结果。它适合不想在构建里写死区域的全球产品。FixedRegion 会跳过区域探测，连接更快，但区域被编译进构建；Dashboard 的 Manage → Edit Allowlist 可以限制客户端可见区域。

- 全球项目优先 Best Region，再用白名单控制可接入区域。
- 中国区确定只面向国内用户时，可用 FixedRegion = "cn"，并配置本地 NameServer。
- 区域白名单为空或格式错误时可能允许全部区域；修改后应复核。
- Best Region 不是确定性结果：延迟接近时，不同设备可能落到不同区域。

## 4. 最小连接代码

Realtime 5 的 C# 路径使用 RealtimeClient，而不是继承 LoadBalancingClient 的旧式写法。下面的结构展示关键步骤；实际回调接口名称请对照当前 SDK 示例。

**C# / Realtime**
```
// Official docs: https://doc.photonengine.com/realtime/current/getting-started/quick-start
// China differences: https://vibrantlink.com/resources/realtime-china-region
// Quota & pricing: https://vibrantlink.com/pricing

var settings = new AppSettings {
    AppIdRealtime = "<APP_ID>",
    AppVersion = "1.0"
    // FixedRegion = "cn" 仅在需要固定区域时设置
};

var client = new RealtimeClient();
client.AddCallbackTarget(this);
client.ConnectUsingSettings(settings);

void Update() {
    client.Service(); // 必须持续泵网络消息
}
```

> **连接是异步的**
>
> ConnectUsingSettings() 不会阻塞等待连接完成。请把匹配与进房逻辑放在 OnConnectedToMaster 回调中，并确保每帧或固定间隔调用 Service()。

## 5. 创建或加入房间

连接 Master Server 后，最短路程是加入或创建房间。你可以指定房名、随机匹配，或使用 Matchmaking Ticket 对接外部匹配。房间的可见性与最大人数由 RoomOptions 控制。

**C# / 房间**
```
// 随机加入；没有合适房间时创建
client.OpJoinRandomOrCreateRoom(null, null);

// 或指定可见房间
var enterRoom = new EnterRoomParams {
    RoomName = "room-1",
    RoomOptions = new RoomOptions { MaxPlayers = 4, IsVisible = true }
};
client.OpCreateRoom(enterRoom);
```

进入房间后会收到 OnJoinedRoom 回调。之后的房间属性、玩家属性和事件都以该房间为上下文；进入房间后不能同时进行大厅匹配，需要先离开房间。

## 6. 发送与接收事件

事件用于高频、实时数据，例如位置、输入、房间内操作。事件码 1–199 可供项目使用，200 及以上由 Photon 保留。可靠发送适合重要状态，不可靠发送适合可丢弃的高频更新。

**C# / RaiseEvent**
```
// 发送
client.OpRaiseEvent(
    1,
    data,
    RaiseEventOptions.Default,
    SendOptions.SendReliable
);

// 接收：实现 IOnEventCallback
void OnEvent(EventData eventData) {
    if (eventData.Code == 1) {
        // 读取数据并更新游戏状态
    }
}
```

事件与操作响应是两条独立通道；不要假设事件返回顺序与操作一致。对必须按顺序处理的逻辑，应放入操作/房间状态或显式带上序号并在业务层处理。

## 7. 两个客户端验收

1. 在 Unity Editor 运行一个客户端，再启动一个独立构建。
2. 两端使用同一个 AppID、AppVersion 和区域。
3. 确认 OnConnectedToMaster → OnJoinedRoom → OnEvent 全链路。
4. 检查房间人数、属性和断线重连是否符合预期。
5. 如失败，临时提高日志级别并先查 AppID 类型、区域白名单和协议端口。

## 8. 中国区接入注意

**Photon Cloud 中国区检查表**
| 项目 | 建议 | 说明 |
| --- | --- | --- |
| AppID | 使用中国区解锁 AppID | 独立 AppID 是光子建议，便于隔离缓存、白名单与计费 |
| 构建 | 单独的中国区构建 | 光子要求为国内环境制作单独构建 |
| NameServer | ns.photonengine.cn | 不要依赖可能被阻断的全球 NameServer |
| 区域 | cn / 中国 | 需要时固定区域，否则用白名单约束 Best Region |
| 容量 | 中国区公开 500 CCU 订阅 | 更大规模需商务定制 |
| Voice | 中国区云不可用 | 如必须使用语音，评估 Photon Server 自建 |

中国区付费方案通常不能直接在 Dashboard 购买，需要工单或商务报价；开发免费额度不得用于商业运营。

海外客户端连接中国区通常效果较差；中国区服务器访问境外自定义认证、Webhook 或 WebRPC 也可能不稳定。上线前应在国内真实网络环境完成端到端测试。

## 9. 下一步

完成最小房间后，再逐项加入认证、匹配、房间属性、重连和监控。若项目需要客户端预测或确定性模拟，不要在 Realtime 上手写复杂网络层，直接评估 Fusion 或 Quantum。

## 参考来源

- Realtime 5 Unity 快速开始: https://doc.photonengine.com/realtime/current/getting-started/quick-start
- Realtime 5 C# 工作流: https://doc.photonengine.com/realtime/current/connection-and-authentication/realtime-workflow-cs
- 如何获取 AppID: https://doc.photonengine.com/realtime/current/getting-started/obtain-your-app-id
- PUN 2 初始设置: https://doc.photonengine.com/pun/current/getting-started/initial-setup
- Photon 价格页: https://www.photonengine.com/pricing

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