日志回捞用于排查设备端播放问题。SDK 在本地记录日志，并查询服务端下发的回捞任务；任务匹配设备及时间范围后，SDK 上传日志，供火山引擎技术支持团队分析。开启日志回捞不代表立即上传全部日志。

前提条件 #

Flutter 播放器 SDK 版本为 1.52.11 及以上版本。集成方法请参见集成 SDK。

开启日志回捞 #

在首次调用 startWithConfiguration 前，将 TTSDKLogConfiguration 设置到初始化配置。最简配置只需指定 enable: true，其余字段采用原生 SDK 默认值。

final config = TTSDKConfiguration.defaultConfigurationWithAppIDAndLicPath(
  appID: 'YOUR_APP_ID',
  licenseFilePath: 'assets/VEVod.license',
  channel: 'your-channel',
);
config.logConfiguration = const TTSDKLogConfiguration(enable: true);
await FlutterTTSDKManager.startWithConfiguration(config);

若应用已有初始化逻辑，在原有配置中加入 logConfiguration 即可，不要重复初始化 SDK。

需要调整日志级别或磁盘占用时，可在初始化前使用以下配置：

config.logConfiguration = const TTSDKLogConfiguration(
  enable: true,
  logLevel: TTSDKLogLevel.debug,
  maxLogSizeM: 50,
  singleLogSizeM: 5,
);

配置参数与默认行为 #

容量和时长需为正整数且不超过 2147483647。单文件容量不能超过日志总容量，包括未填写字段的默认值。路径和设备标识若填写则不能为空。无效配置会在调用原生初始化前抛出 ArgumentError。

• 未设置配置：logConfiguration 为 null 时，Flutter 不覆盖原生及服务端配置，不能据此认定日志回捞已开启。
• 显式开启或关闭：enable: true 开启本地记录与回捞任务查询，enable: false 显式关闭。iOS 的显式关闭优先于服务端开启配置；需要保留服务端控制能力时，应不设置 logConfiguration。
• 调试输出：openAllLog() 用于调试日志输出，不能代替日志回捞配置。开启日志回捞无需调用 openAllLog()。

发起回捞与确认结果 #

1. 开启日志回捞后启动应用，完成播放并复现问题，记录问题发生时间、时区、设备系统及应用版本。
2. 获取回捞设备 ID。未配置自定义 deviceID 时，使用 getDeviceID() 返回的默认设备标识；若尚未生成，稍后重试。若设置了自定义 deviceID，则使用配置中的值。
3. 将设备 ID、问题时间范围与现象提供给火山引擎技术支持团队，由其创建对应回捞任务。
4. 让设备运行应用并保持网络可用，确认设备查询到任务并完成上传，再由技术支持核实服务端日志可用。

// SDK 初始化完成后获取默认回捞设备标识。
final deviceId = await FlutterTTSDKManager.getDeviceID();

仅初始化成功、本地生成日志文件或 App 构建成功，都不能证明回捞上传成功。验收应覆盖任务下发、设备查询、上传以及服务端日志可用的完整流程。

常见问题 #

为什么开关打开后没有立即上传？ #

本地记录与服务端回捞任务是两个步骤。检查是否已完全重启应用、设备 ID 和问题时间范围是否匹配，以及服务端是否已创建任务。

如何关闭日志回捞？ #

在首次初始化前传入 TTSDKLogConfiguration(enable: false)。修改配置后，完全退出并重新启动应用。

如何恢复 SDK 默认策略？ #

不设置 logConfiguration，并完全退出并重新启动应用。恢复默认不等同于显式开启。

相关文档 #

• Android 获取 SDK 日志
• iOS 获取 SDK 日志