跳到主要内容
VibrantLink 动联无限
快速开始中文指南

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

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

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

阅读约 7 分钟更新于 2026 年 11 月 15 日光子原文
本页目录
  1. 01 · 先分清 Cloud、Realtime 与 PUN
  2. 02 · 创建正确的 AppID
  3. 03 · 选择区域:Best Region、固定区域与白名单
  4. 04 · 最小连接代码
  5. 05 · 创建或加入房间
  6. 06 · 发送与接收事件
  7. 07 · 两个客户端验收
  8. 08 · 中国区接入注意
  9. 09 · 下一步

这篇指南用较短路径带你创建第一个可用的 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

  1. 登录 Photon Dashboard,创建一个 Realtime 类型的应用。
  2. AppID 是 GUID,只能用于对应产品;Chat、Voice 和 Realtime 不要混用。
  3. 如果面向国内玩家,请通过 Photon 控制台或联系渠道为这个 AppID 申请中国区解锁。
  4. 不要公开贴出完整 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两个客户端验收

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

08中国区接入注意

Photon Cloud 中国区检查表
项目建议说明
AppID使用中国区解锁 AppID独立 AppID 是光子建议,便于隔离缓存、白名单与计费
构建单独的中国区构建光子要求为国内环境制作单独构建
NameServerns.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、区域、许可与部署问题,可以带着项目背景直接询问。 我们不会索要账号密码。