排查接入问题

接入异常时，先找出最早没有完成的步骤，再检查这一步的输入、返回值和回调。不要一开始就混在一起检查设备启动、连接、送流和播放，也不要只凭“接口返回成功”判断后续步骤已经完成。

先从概览确认问题发生在哪一步，再按本页检查最早未完成的结果。仍无法定位时，收集同一次复现的返回值、关键回调和日志。

先确认问题停在哪个阶段

1. SDK 没有完成初始化或启动

客户端先检查 TiRtc.initialize(...) 的返回值或初始化结果，再进入连接流程。
C SDK 中，TiRtcStart() 返回 0 只表示启动请求已经提交；收到 TIRTC_EVENT_SYS_STARTED 才表示启动完成。
对照当前平台的接入 SDK页面检查要求。C SDK 还要确认二进制包与目标平台匹配、日志出口已经可用。

如果 SDK 尚未启动完成，不要继续排查连接和音视频。

2. 客户端和设备端没有建立连接

先对照连接设备检查：

设备端是否已经启动并在线，客户端的 remote_id 是否就是目标 device_id。
本次连接使用的 token 是否为当前目标设备签发；重新连接或连接失败后重试时，重新签发一次性 token。
客户端是否达到当前平台的连接建立标志，设备端是否收到 on_conn_accepted(hconn)。只进入中间状态或只拿到同步受理结果，不表示连接已经建立。
C SDK 一端收到 on_conn_error 后，是否把 hconn 投递到业务线程，再调用 TiRtcDisconnect(hconn) 完成清理；重连时不要继续使用旧连接句柄。

如果要先排除真实设备和业务环境的影响，可以使用 CLI 进行接入联调，用模拟设备端和开发期 token 搭建验证环境。

3. 已连接，但没有声音或画面

连接成功只说明传输链路已经建立。继续按照已连接但没有声音或画面依次确认：

客户端是否发起订阅，或设备端是否按业务约定在连接后直接送流。
设备端发送、客户端订阅和播放使用的 stream_id 是否一致。
编码格式、完整帧、首个关键帧、参数集、毫秒时间戳和帧长度是否符合要求。
客户端输出是否绑定当前连接并进入播放或渲染状态。

4. 连接后的单项能力不符合预期

连接成功后，分别排查每项功能，不要把其中一项当成另一项的前置条件：

对讲没有声音：检查语音对讲的常见问题。
命令没有进入预期分支：检查收发命令消息中的常见问题。
流消息无法解析：检查收发流消息中的常见问题。

问题仍未解决时收集证据

完成对应阶段的检查后仍然无法定位，再获取 SDK 日志并交给技术支持。问题复现后尽快获取日志，避免后续运行覆盖本次记录。日志要和问题发生时间、实际现象、返回值及回调结果属于同一次复现。

上传客户端日志

dart

final ({int code, String? logId}) result = await TiRtcLogging.upload();

if (result.code == 0 && result.logId != null) {
  debugPrint('TiRTC logId: ${result.logId}');
} else {
  debugPrint('TiRTC log upload failed, code=${result.code}');
}

tsx

import {TiRtcLogging} from 'tirtc-react-native';

const result = await TiRtcLogging.upload();
if (result.code === 0 && result.logId !== null) {
  console.info(`TiRTC logId: ${result.logId}`);
} else {
  console.warn(`TiRTC log upload failed, code=${result.code}`);
}

kotlin

val accepted = TiRtcLogging.upload { code, logId ->
  if (code == 0 && logId != null) {
    Log.i("TiRTC", "logId=$logId")
  } else {
    Log.w("TiRTC", "upload failed, code=$code")
  }
}

if (accepted != 0) {
  Log.w("TiRTC", "upload request not accepted, code=$accepted")
}

import { TiRtcLogging } from 'tirtc/Index';

const result = await TiRtcLogging.upload();
if (result.code === 0 && result.logId !== undefined && result.logId.length > 0) {
  console.info(`TiRTC logId: ${result.logId}`);
} else {
  console.warn(`TiRTC log upload failed, code=${result.code}`);
}

swift

let accepted = TiRtcLogging.upload { result in
    if result.succeeded, let logId = result.logId {
        print("TiRTC logId: \(logId)")
    } else {
        print("TiRTC log upload failed, code=\(result.code)")
    }
}

if accepted != 0 {
    print("TiRTC log upload request not accepted, code=\(accepted)")
}

上传成功后，记录返回的 logId。Android 和 iOS 的返回值表示上传请求是否已受理，最终结果以回调为准。其他平台直接等待上传结果。

获取 C SDK 日志

C SDK 不提供日志上传接口，需要从设备取得原始日志。建议在设备投入使用前参考配置 SDK 日志输出，根据平台决定是实时输出、由 SDK 保存文件，还是通过回调交给应用保存或转发。

问题复现后，按已经配置的日志出口取回记录：

Linux 文件日志：复制配置路径下的日志文件。文件会滚动覆盖，应在复现后尽快取得。
应用日志链路：从平台日志系统、存储卡、环形缓冲区或上传通道中导出同一时间段的原始内容。
仅输出到控制台：保存本次复现期间的完整控制台输出。如果问题已经发生且没有留存控制台内容，历史日志无法补回，需要先增加持久化保存或回调处理，再次复现。

联系技术支持时提供

logId 或 C SDK 原始日志。
使用的平台和 SDK 版本。
问题发生时间、实际现象、最短复现步骤，以及问题停在哪个阶段。
关键接口的返回值和相关状态或错误回调。
日志上传失败时返回的错误码。

如果问题发生在设备与应用的交互过程中，请提供同一次复现的两侧日志。提交前请移除 token、SecretKeyId、device_secret_key 等敏感信息。

排查接入问题 ​

先确认问题停在哪个阶段 ​

1. SDK 没有完成初始化或启动 ​

2. 客户端和设备端没有建立连接 ​

3. 已连接，但没有声音或画面 ​

4. 连接后的单项能力不符合预期 ​

问题仍未解决时收集证据 ​

上传客户端日志 ​

获取 C SDK 日志 ​

联系技术支持时提供 ​