把“视频不能播”写成别人能复现的 HLS 问题报告

“视频不能播”可能完全属实，但下一位接手的人仍然几乎什么都不知道：哪个页面？什么来源？是按下按钮没有反应，还是画面冻结、声音消失？

有用的播放报告，应该让别人不用再开一轮对话，也能还原你观察到的现象。它可以只有几段话，关键是保留必要事实，并把事实与猜测分开。

从一个失败动作开始

先用普通语言写任务：“打开播放器页面，载入允许测试的来源 A，点击播放，观看前面一段。”再说明预期在哪一步落空。

不要把多个无关问题塞进同一组复现步骤。加载失败与缺少字幕选项，可能需要分别处理。第一份报告先围绕阻止主要观看任务的那个问题展开。

保留必要环境

记录浏览器及版本、操作系统、页面地址、日期、时间和时区。如果无痕窗口、公司网络、需要登录的来源等条件与现象有关，也一起写明。

不必公开完整电脑清单。目的是保留别人能够理解的测试条件。“桌面浏览器”通常太笼统，但在没有关联证据时，罗列所有无关扩展也没有帮助。

把预期、观察与推测分开

这样可以防止“怀疑的原因”变成“大家默认的事实”。如果还没有相关证据，就先写“CORS 坏了”，接手的人可能因此忽略其他原因。

浏览器媒体元素有播放状态与错误状态，但报告应保留实际观察，不能只凭某一个状态保证诊断。技术信息只有能缩小下一步检查范围时，才真正有用。

使用安全的来源标识

保留足够识别来源的信息，同时避免把凭据写进公开报告。一个来源代号、直播或点播类型，以及经认可的私密获取方式，可能就已足够。

分享网络记录或截图前先检查。请求地址、Cookie、请求头和账号信息可能出现在里面。遮去能够提供访问权限的值，并说明哪些部分做了脱敏。脱敏示例是证据，不一定能够直接重新播放。

可以直接套用的报告

• 任务： 我想完成什么。
• 环境： 浏览器及版本、系统、页面和相关会话条件。
• 时间： 日期、时间和时区。
• 来源： 安全代号、直播或点播、访问条件。
• 步骤： 能重现观察的最短操作顺序。
• 预期： 原本应该发生什么。
• 实际： 真正发生了什么，包括可见提示。
• 证据： 脱敏截图或相关输出。
• 对照： 如果做过，只写一次条件可比较的第二组测试。
• 下一项： 希望接手者继续确认的一个问题。

无法稳定重现时，就明确写出来。“出现一次，之后两次成功”是有用信息。改写成“总是失败”，反而丢失了重要条件。

让交接落到能行动的人手里

把报告交给能处理剩余问题的人。需要来源所有者核对访问权限时，详细描述页面布局并不是主要证据。如果页面在允许使用的公开样例下也能稳定失败，实际地址和复现步骤就更关键。

浏览器流测试和播放列表检查器可以帮助补充相关观察。不要为了让报告“更技术化”，附上一堆与现象无关的工具输出。

技术参考

HTML 媒体规范定义了浏览器媒体行为与错误状态。本文的报告模板属于保存复现信息的编辑方法。