产品手册 · 清单格式与播放
西瓜.m3u8 是一份怎样的播放清单
西瓜.m3u8 指一份以 UTF-8 编码保存、扩展名为 .m3u8 的播放清单文本文件。它不存放画面，也不容纳音频流，而是用一行行纯文本把播放器需要的线索排好队：哪一段先播、每段多长、片段从哪个地址取、是否加密、有没有多套码率可选。把这份文件打开，就像展开一张写给播放器的施工图。
下面按“清单结构 → 播放路径 → 参数对照 → 常见问题”的顺序，把这类文件从写法到实际播放逐层讲清，方便你在桌面、手机与浏览器三端分别找到合适的打开方式。
逐行解读：西瓜.m3u8 的标签与地址
清单的第 8 行与第 3 行往往看不出区别，但播放器正是靠这些以 # 开头的标签决定行为。下面按出现顺序梳理最常用的一组。
- 01#EXTM3U
首行标记，必须存在。播放器见到它才确认这是一份可解析的清单，而不是随手保存的文本。
- 02#EXT-X-VERSION
声明清单遵循的兼容版本。版本号影响哪些标签可以被理解，写得过高会让旧播放器直接放弃解析。
- 03#EXT-X-TARGETDURATION / #EXTINF
前者给出分片时长的整体上限，后者逐条标注紧随其后的那一段分片有多长。二者配合，播放器才能估算缓冲与切换时机。
- 04#EXT-X-KEY
加密标记。出现时说明分片受保护，并指明解密方式与密钥地址的书写形式；没有这一行则表示分片可直接读取。
- 05分片地址行
紧跟在 #EXTINF 下面的普通文本行，可以是相对路径，也可以是完整地址。相对路径会以清单所在位置为基准拼接。
- 06#EXT-X-STREAM-INF
主清单中出现，用于列出多套码率。每一行后面跟着一路独立清单的地址，播放器据此在流畅与清晰之间自动切换。
一个容易忽略的细节：清单里的空行通常只是排版，不影响解析；但标签与它要描述的地址行之间不能插入无关行。
三端播放路径：桌面、手机与浏览器
同一份西瓜.m3u8，在不同设备上的处境并不一样。下面按使用场景给出可操作的路径。
- 桌面把清单文件直接拖入支持 HLS 的播放器窗口，或在其“打开网络串流”菜单里填入清单地址。桌面播放器普遍对 #EXT-X-KEY 与多码率主清单的支持较完整，适合作为排查问题的第一站。
- 手机系统自带播放器多数只认本地视频文件，遇到清单地址常常没有反应。此时可安装具备网络串流能力的播放 App，或把地址交给支持 HLS 的浏览器完成加载。
- 浏览器Safari 系内核原生支持 HLS，可以直接打开清单地址；基于 Chromium 的浏览器通常需要借助 HLS 加载脚本把清单转成可播放的媒体源。若页面内置了该类脚本，直接粘贴地址即可。
- 转存需要留存时，可将清单连同分片合并为一个完整文件。清单只是索引，单独保存西瓜.m3u8 而丢下分片，文件是无法还原成视频的。
参数与兼容性对照
下表把常见标签、它们的作用以及在各端需要注意的差异放在一处，便于快速核对。
| 标签 / 参数 | 作用 | 桌面 | 移动端 |
|---|---|---|---|
#EXTM3U | 清单身份声明，首行必需 | 必须 | 必须 |
#EXTINF | 标注单段分片时长 | 普遍支持 | 多数支持 |
#EXT-X-KEY | 声明加密方式与密钥位置 | 支持较完整 | 视 App 而定 |
#EXT-X-STREAM-INF | 列出多码率清单，供自动切换 | 支持 | 部分支持 |
#EXT-X-ENDLIST | 标记清单已结束，非直播 | 支持 | 支持 |
对照表只描述格式层面的常见差异，具体表现仍取决于播放器的实现版本。
常见问题
西瓜.m3u8 打不开，先检查什么？
依次确认三件事：文件首行是否为 #EXTM3U；分片地址是相对路径还是绝对地址，前者需要与清单保持原有目录关系；地址是否带多余的空格或全角符号。多数“打不开”都出在这三处。
为什么只有画面没有声音，或者只播几秒就停？
清单本身不携带音视频，只做索引。若分片缺失或地址失效，播放器拿到前几段后就会停住。可核对清单中地址行的数量与分片实际是否齐全。
清单里出现多路地址，播放器会选哪一个？
存在 #EXT-X-STREAM-INF 时，播放器会结合网络状况与设备能力挑选一路；只有单路清单时则没有选择余地，直接播放即可。
可以只用浏览器播放吗？
Safari 系内核可原生播放；其余内核往往需要页面预先引入 HLS 加载脚本。若页面已自带该能力，把清单地址粘贴进去就能开始。