本页目录
这篇指南用较短路径带你创建第一个可用的 Photon Cloud 房间。先理解 AppID、区域、房间与事件这四件事,再结合实际 SDK 查看 API 与中国区、全球区的差异。
截至 2026-11,Cloud 是托管服务;Realtime 是房间与事件基础层;PUN 2 是 Unity 封装,处于维护 / LTS 模式。
AppID 是 Photon 产品级标识,Chat、Voice 需要各自 AppID;中国区 AppID 还要单独解锁。
客户端必须持续调用 Service() 处理网络消息,ConnectUsingSettings() 返回并不等于连接完成。
中国区建议独立构建;独立 AppID 是光子建议而非所有场景的技术强制。
01先分清 Cloud、Realtime 与 PUN
Photon Cloud 是托管运行时,Realtime 是房间、匹配、事件与认证的底层 API。PUN 2 则是 Unity 侧的房间制封装,底层使用 Realtime。当前 PUN 2 已进入 maintenance / LTS 模式:存量项目继续支持,但新项目应评估 Fusion 或 Quantum。
下面的最短路径根据 Realtime 5 与 PUN 2 的当前光子文档整理。不同 SDK 版本的类名可能略有变化,发布前请以你实际使用的版本为准。
02创建正确的 AppID
- 登录 Photon Dashboard,创建一个 Realtime 类型的应用。
- AppID 是 GUID,只能用于对应产品;Chat、Voice 和 Realtime 不要混用。
- 如果面向国内玩家,请通过 Photon 控制台或联系渠道为这个 AppID 申请中国区解锁。
- 不要公开贴出完整 AppID;联系支持时通常只需前 8 位。
中国区不是只改一个区域字符串
中国区 AppID 需要单独解锁,光子要求为国内环境制作单独构建,并建议使用独立 AppID。客户端还必须使用本地 NameServer ns.photonengine.cn。
03选择区域:Best Region、固定区域与白名单
不指定区域时,客户端默认使用 Best Region:NameServer 返回区域列表,客户端 ping 后选择结果。它适合不想在构建里写死区域的全球产品。FixedRegion 会跳过区域探测,连接更快,但区域被编译进构建;Dashboard 的 Manage → Edit Allowlist 可以限制客户端可见区域。
- 全球项目优先 Best Region,再用白名单控制可接入区域。
- 中国区确定只面向国内用户时,可用 FixedRegion = "cn",并配置本地 NameServer。
- 区域白名单为空或格式错误时可能允许全部区域;修改后应复核。
- Best Region 不是确定性结果:延迟接近时,不同设备可能落到不同区域。
04最小连接代码
Realtime 5 的 C# 路径使用 RealtimeClient,而不是继承 LoadBalancingClient 的旧式写法。下面的结构展示关键步骤;实际回调接口名称请对照当前 SDK 示例。
C# / Realtime
verify against target SDK// 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()。
05创建或加入房间
连接 Master Server 后,最短路程是加入或创建房间。你可以指定房名、随机匹配,或使用 Matchmaking Ticket 对接外部匹配。房间的可见性与最大人数由 RoomOptions 控制。
C# / 房间
verify against target SDK// 随机加入;没有合适房间时创建
client.OpJoinRandomOrCreateRoom(null, null);
// 或指定可见房间
var enterRoom = new EnterRoomParams {
RoomName = "room-1",
RoomOptions = new RoomOptions { MaxPlayers = 4, IsVisible = true }
};
client.OpCreateRoom(enterRoom);进入房间后会收到 OnJoinedRoom 回调。之后的房间属性、玩家属性和事件都以该房间为上下文;进入房间后不能同时进行大厅匹配,需要先离开房间。
06发送与接收事件
事件用于高频、实时数据,例如位置、输入、房间内操作。事件码 1–199 可供项目使用,200 及以上由 Photon 保留。可靠发送适合重要状态,不可靠发送适合可丢弃的高频更新。
C# / RaiseEvent
verify against target SDK// 发送
client.OpRaiseEvent(
1,
data,
RaiseEventOptions.Default,
SendOptions.SendReliable
);
// 接收:实现 IOnEventCallback
void OnEvent(EventData eventData) {
if (eventData.Code == 1) {
// 读取数据并更新游戏状态
}
}事件与操作响应是两条独立通道;不要假设事件返回顺序与操作一致。对必须按顺序处理的逻辑,应放入操作/房间状态或显式带上序号并在业务层处理。
07两个客户端验收
- 在 Unity Editor 运行一个客户端,再启动一个独立构建。
- 两端使用同一个 AppID、AppVersion 和区域。
- 确认 OnConnectedToMaster → OnJoinedRoom → OnEvent 全链路。
- 检查房间人数、属性和断线重连是否符合预期。
- 如失败,临时提高日志级别并先查 AppID 类型、区域白名单和协议端口。
08中国区接入注意
| 项目 | 建议 | 说明 |
|---|---|---|
| AppID | 使用中国区解锁 AppID | 独立 AppID 是光子建议,便于隔离缓存、白名单与计费 |
| 构建 | 单独的中国区构建 | 光子要求为国内环境制作单独构建 |
| NameServer | ns.photonengine.cn | 不要依赖可能被阻断的全球 NameServer |
| 区域 | cn / 中国 | 需要时固定区域,否则用白名单约束 Best Region |
| 容量 | 中国区公开 500 CCU 订阅 | 更大规模需商务定制 |
| Voice | 中国区云不可用 | 如必须使用语音,评估 Photon Server 自建 |
中国区付费方案通常不能直接在 Dashboard 购买,需要工单或商务报价;开发免费额度不得用于商业运营。
海外客户端连接中国区通常效果较差;中国区服务器访问境外自定义认证、Webhook 或 WebRPC 也可能不稳定。上线前应在国内真实网络环境完成端到端测试。
09下一步
完成最小房间后,再逐项加入认证、匹配、房间属性、重连和监控。若项目需要客户端预测或确定性模拟,不要在 Realtime 上手写复杂网络层,直接评估 Fusion 或 Quantum。
Official sources
本文依据上述光子文档整理与翻译,仅供中文接入参考。若与光子英文文档、SDK 实际行为或双方合同不一致,以光子资料与合同为准。
旧地址 /5minsphotoncloud/ 会永久跳转到本页,原有链接仍可访问。
Need help?
把文档里的步骤,落到你的项目里。
中国区 AppID、区域、许可与部署问题,可以带着项目背景直接询问。 我们不会索要账号密码。
Related products