PAYATHON 2026

Agora Web SDK 跨频道转发报 invalid_appid 如何排查？

数据小陈

结论

Agora 的跨频道媒体转发需要联系 Agora 开通。先确认当前 App ID 对应的项目已开通该能力。前后端 App ID 一致、普通频道能够加入，都不能替代这项确认。Agora Web 跨频道转发指南明确列出了这一前提。

仅凭这条 invalid_appid 日志，还不能断定原因是未开通。现有信息也不足以确认 token 的生成参数、源频道 UID 的使用方式，以及调用前是否已完成 publish。

先检查项目是否开通转发能力

向 Agora 技术支持确认，实际传入 client.join() 的 App ID 是否已经开通 cross-channel media stream relay。核对运行时使用的项目，避免只确认了控制台里的另一个测试项目。

错误中出现了 cross channel app center error，因此可以优先检查项目是否开通了转发能力。这只是排查方向，不能视为官方对该错误的唯一归因。

同时核对三个位置的实际值：

  • 前端传给 client.join() 的 App ID。
  • 后端生成源频道 relay token 时使用的 App ID。
  • 后端生成目标频道 relay token 时使用的 App ID。

使用自己的 token server 只说明 token 的来源，还要确认生成 token 时选用了同一个项目及其对应的 App Certificate。

分清加入频道和转发使用的 token

不要默认将主播加入源频道的 token 直接作为 srcToken 使用。

已核对的 Web SDK v4.24.1 ChannelMediaRelayInfo API 文档规定，源频道的 relay token 使用源频道名和 uid = 0 生成；目标频道的 token 使用目标频道名和目标 relay UID 生成。ChannelMediaRelayInfo API

可以按用途检查后端签发参数：

token 用途channelName生成 token 时的 UID
主播加入源频道源频道名主播加入频道使用的 UID
源频道 relay token源频道名0，按上述 API 文档要求
目标频道 relay token目标频道名addDestChannelInfo 中配置的 UID

还要检查 token 是否过期、频道名是否完全一致，以及所授予的权限是否满足转发用途。输入没有给出 token server 的实现，不能仅凭变量名判断这些条件已经满足。

UID 配置要结合 SDK 版本确认

源频道和目标频道的 UID 不必使用相同数值。目标 relay UID 不能与目标频道内已有用户的 UID 冲突；跨频道转发也不支持字符串 UID。

关于源配置中的 UID，官方资料有表述差异：Web SDK v4.24.1 API 文档要求使用被转发主播的 UID，Web 转发指南则建议使用不同于主播的 UID，优先设为 0。因此，在不知道实际 SDK 版本时，不能直接认定 uid: joinedUid 一定错误。API 文档、Web 转发指南

应补充实际安装的 agora-rtc-sdk-ng 版本，并请 Agora 支持确认该版本的源 UID 配置要求。源配置中的 UID 和生成源 relay token 时使用的 UID 也应分别核对。

在 publish 成功后启动转发

CONNECTED 不能证明本地媒体流已经发布。Web 转发指南要求在 publish 后调用 startChannelMediaRelay；在直播频道中，调用者还必须是 host。Web 转发指南

下面的示例按上述 v4.24.1 API 文档对源 UID 的说明组织。假设 client 已作为 host 加入源频道，localTracks 已创建，两个 relay token 已由后端按对应参数签发：

// Register these listeners once, before starting the relay.
client.on("channel-media-relay-state", (state, code) => {
  console.log("relay state", { state, code });
});

client.on("channel-media-relay-event", (event) => {
  console.log("relay event", event);
});

await client.publish(localTracks);

// destRelayUid must be a numeric UID unused in the destination channel.
// srcRelayToken: generated with sourceChannel and uid = 0.
// destRelayToken: generated with destChannel and destRelayUid.
const config = AgoraRTC.createChannelMediaRelayConfiguration();

config.setSrcChannelInfo({
  channelName: sourceChannel,
  uid: joinedUid,
  token: srcRelayToken,
});

config.addDestChannelInfo({
  channelName: destChannel,
  uid: destRelayUid,
  token: destRelayToken,
});

try {
  await client.startChannelMediaRelay(config);
} catch (error) {
  console.error("startChannelMediaRelay failed", error);
}

示例将 srcRelayToken 与加入频道的 token 分开命名，方便检查签发参数。该示例不能替代项目能力开通，也没有在当前应用环境中运行验证。

仍然失败时补充哪些信息

如果已确认项目开通，且发布与 token 配置均符合所用版本的要求，可以向 Agora 支持提供 SDK 版本、失败时间及其时区、完整错误、relay 状态和事件日志，以及脱敏后的频道名、UID 和 token 生成参数。不要提交 App Certificate 或完整 token。

在 React 中，还应确认没有因 effect 重复执行而并发启动转发。成功启动后，需要变更目标频道时使用 updateChannelMediaRelay；再次启动前按接口要求先停止已有转发。状态与事件回调的定义可参照 AgoraRTCClient API。

备注：内容仅供参考。