跳到主要内容
清单参考手册

HLS 播放列表 M3U8 标签参考手册

解析主播放列表与媒体播放列表中的标签，了解每个标签所控制的 URI，将清单文本转化为精准的播放排错依据。

更新于 2026年8月1日 由 M3U8 免费在线播放器维护 11 分钟阅读

HLS 播放列表是 UTF-8 编码的文本文件。以 #EXT 开头的行是标签，URI 所在行指定另一个播放列表或媒体资源，其他以 # 开头的行均为注释。标签名称指明了其后属性所描述的作用域和对象。理解这种对应关系比单纯在文件中搜索单个关键词有用得多。

本指南汇总了 RFC 8216 (HTTP Live Streaming) 中常见的指令。对于其定义的标签，RFC 仍是规范性权威标准。具体实现及后续扩展规范可能会增加新功能，因此若遇到不寻常的播放列表，请对照您实际支持的播放器和分发平台规范进行验证。

首先识别播放列表类型

主播放列表（Master Playlist）描述可用的变体码率流和呈现方式。它通常包含 #EXT-X-STREAM-INF 及其后的子播放列表 URI，以及用于备用音频、字幕或视频的可选 #EXT-X-MEDIA 条目。媒体播放列表（Media Playlist）则描述媒体分片的时序列表，通常包含 #EXTINF、分片 URI 以及时间或序列指令。

切勿将仅适用于主播放列表的标签与仅适用于媒体播放列表的标签混用。排查故障时，首先要确认打开的 URL 是主播放列表还是选定的某个子播放列表。播放器即便成功解析了主列表，仍可能在媒体列表、分片、初始化片段、字幕或密钥请求上发生错误。

各类播放列表中常见的基础标签

标签用途排查诊断问题
#EXTM3U将文档标识为扩展 M3U 播放列表，必须是文件的第一行。源站或登录跳转是否返回了 HTML 错误页面而不是播放列表？
#EXT-X-VERSION指示播放列表特性所需的兼容性版本号。声明的版本是否涵盖了当前使用的语法和属性？
#EXT-X-INDEPENDENT-SEGMENTS声明每个分片中的媒体样本均可独立解码，无需依赖其他分片信息（需符合规范范围）。媒体打包是否确实符合这一独立解码承诺？
#EXT-X-START通过时间偏移量提供首选的起播时间点。请求的时间偏移对于当前直播窗口或点播时长是否合理？

#EXT-X-VERSION 既不是营销标识，也不是简单的编码器版本号。它传达的是播放列表各项特性所需的最低客户端兼容要求。切勿在不清楚可能排斥哪些客户端的情况下盲目提高版本号，也切勿声明低于语法实际要求的过低版本。

主播放列表标签

#EXT-X-STREAM-INF

该标签用于描述一个变体流（Variant Stream）。其中必需的 BANDWIDTH 属性给出了 RFC 定义下的峰值分片码率。常见可选属性包括 AVERAGE-BANDWIDTH、CODECS、RESOLUTION、FRAME-RATE 以及 AUDIO 或 SUBTITLES 等渲染组引用。其下一行的 URI 指定该变体对应的媒体播放列表。

当仅有某一个画质档位播放失败时，可直接打开紧随其后的 URI 进行检查。核对声明的编解码器与实际分片是否匹配、相对路径能否从主 URL 正确解析、以及引用的音频或字幕组是否存在。码率数值应足够准确以供自适应算法选流，它并非推荐给观众的网络带宽。

#EXT-X-MEDIA

该标签用于声明备用呈现版本（Alternative Rendition）。TYPE 指定音频、视频、字幕或隐藏式字幕（Closed Captions）；GROUP-ID 将该呈现与变体条目关联；NAME 提供可读的显示名称。根据类型不同，LANGUAGE、DEFAULT、AUTOSELECT、FORCED、CHARACTERISTICS 和 URI 等属性控制其选择与加载行为。

组引用必须保持一致。如果流条目声明了 AUDIO="stereo"，则必须存在对应的媒体组。同一组内重名、URI 无法访问、或默认选项不满足 RFC 约束，都会导致轨道选择异常。

其他主列表指令

  • #EXT-X-I-FRAME-STREAM-INF 用于描述纯 I 帧变体流，其 URI 直接作为属性给出，而非位于下一行。
  • #EXT-X-SESSION-DATA 携带适用于主播放列表的会话数据。切勿在公开的播放列表元数据中存放机密信息。
  • #EXT-X-SESSION-KEY 允许客户端根据加密方式与格式要求，预先加载变体流所需的加密密钥。

媒体分片与时间标签

#EXTINF

#EXTINF 提供紧随其后的 URI 所代表的媒体分片时长。逗号后的可选文本为分片标题。媒体播放列表中的每个媒体分片都需要一个 #EXTINF 标签。如果时长记录有误，即使文件本身可以正常加载，播放器的时间轴、跳转定位（Seeking）、直播边缘同步或缓冲区计算也可能出现异常。

#EXT-X-TARGETDURATION

该标签根据 RFC 的取整规则定义了媒体分片的最大持续时间，在媒体播放列表中只出现一次。客户端据此决定轮询刷新直播列表的频率。分片时长超过目标时长属于打包错误，而将目标时长设得过大则会拖慢直播列表的刷新频率。

#EXT-X-MEDIA-SEQUENCE

该数值是当前列表中第一个分片的媒体序号。它不必从零开始。在滑动直播窗口中，随着旧分片移出窗口，该值通常递增。如果 CDN 乱序返回了过期的播放列表版本，客户端可能会请求已被删除的分片或误判直播边缘。

#EXT-X-DISCONTINUITY

该标签标记编码参数、时间戳序列或其他媒体特征发生变化的断点。常见原因包括广告插入、信号源切换或时间戳重置。必须将其放置在实际的变化边界处。遗漏断点会导致解码或时间轴错乱；而添加不必要的断点则会迫使播放器进行本可避免的重置。

#EXT-X-DISCONTINUITY-SEQUENCE 允许客户端在多次播放列表更新或不同呈现之间对齐不连续性序列号。它必须出现在首个媒体分片之前，并在直播窗口滑动时保持连贯一致。

控制资源请求方式的标签

#EXT-X-BYTERANGE

该指令表明下一个媒体分片是后续 URI 资源内部的一段字节范围，而非独立的文件对象。它提供长度和可选的偏移量。如果省略偏移量，规范规定其相对于前一个子范围顺延。源站与 CDN 必须正确支持 Range 请求分发，且缓存不得返回错误的字节范围。

#EXT-X-MAP

该标签指定解析后续分片所需的媒体初始化片段（常用于 Fragmented MP4）。其 URI 可附带 BYTERANGE。即使播放列表和分片都能成功下载，如果初始化资源缺失、被拦截、过期或加密方式不一致，播放依然会失败。

#EXT-X-KEY

该指令指定后续媒体分片的加密方式。属性包括 METHOD，并根据方法包含密钥 URI、初始化向量 (IV)、密钥格式或格式版本。该设置持续生效直至下一个密钥指令覆盖。METHOD=NONE 表示后续分片未加密。

在不泄露密钥内容的前提下调试密钥请求。在浏览器必须请求密钥的环境中，重点检查请求状态、鉴权机制、Token 有效期、域名以及 CORS 跨域配置。DRM 许可证工作流与普通的 AES-128 密钥获取机制不可混为一谈。

播放列表生命周期标签

#EXT-X-ENDLIST

该标签表明播放列表不会再追加新的媒体分片。对于已录制完成的点播 (VOD) 列表这是必需的，也可在直播活动结束时出现。没有该标签的直播列表会持续轮询更新。过早添加会导致播放内容截断；而在已完成的点播中遗漏它，则会导致客户端不断进行无用的轮询请求。

#EXT-X-PLAYLIST-TYPE

取值 EVENT 和 VOD 描述了可变性约束。事件 (EVENT) 播放列表可在保留历史条目的同时向后追加。点播 (VOD) 播放列表内容完全固定不变。滑动直播窗口通常省略此标签，因为随着媒体序号递增，旧条目会被移除。

#EXT-X-PROGRAM-DATE-TIME

该标签将后续媒体分片的首个样本与绝对日期和时间关联起来。它有助于对齐多路音视频流、节目指南 (EPG)、服务器日志和定时元数据。模棱两可或非单调的时间戳会导致故障排查难以还原时间线，因此应输出准确的时间戳并包含时区标识。

主列表与媒体列表范例解析

以下是一个简易主播放列表，将两个画质变体连接到一个备用音频组：

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="audio",NAME="English",DEFAULT=YES,AUTOSELECT=YES,URI="audio/en.m3u8"
#EXT-X-STREAM-INF:BANDWIDTH=1800000,AVERAGE-BANDWIDTH=1500000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2",AUDIO="audio"
video/720p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=850000,AVERAGE-BANDWIDTH=700000,RESOLUTION=854x480,CODECS="avc1.4d401e,mp4a.40.2",AUDIO="audio"
video/480p.m3u8

下面的点播媒体播放列表使用了一个初始化映射文件和三个分片。分片时长必须符合目标时长规则，结尾的结束标记表明列表已完整：

#EXTM3U
#EXT-X-VERSION:7
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MAP:URI="init.mp4"
#EXTINF:6.000,
segment-000.m4s
#EXTINF:6.000,
segment-001.m4s
#EXTINF:4.500,
segment-002.m4s
#EXT-X-ENDLIST

示例展示的是对应关系，而非万能的编码公式。所需的版本号、编解码器字符串、分片时长和封装选择必须与实际生成的媒体及目标客户端相匹配。

异常播放列表的排查顺序

  1. 确认响应主体为以 #EXTM3U 开头的 UTF-8 文本播放列表，而不是 HTML 错误页面。
  2. 区分其为主播放列表还是媒体播放列表，检查是否存在特定类型标签的错误混用。
  3. 根据包含该相对路径的播放列表 URL，解析每个相对 URI。
  4. 对于主播放列表：核实每个变体与呈现组的引用关系、编解码器声明以及子播放列表 URI。
  5. 对于媒体播放列表：核查目标时长、分片时长、序列号推进、断点、初始化片段、密钥及结束状态。
  6. 单独请求首个加载失败的子资源，对比 HTTP 状态码、响应体、MIME 类型、CORS 响应头、缓存时间和鉴权状态。
  7. 将清单声明与实际媒体数据进行对比，切勿单纯认为标签语法正确就代表编码格式合规。

常见清单配置错误

  • 主播放列表引用的子路径相对目录与打包工具预期的目录不一致。
  • 变体声明的编解码器与实际音视频样本不相符。
  • 引用了备用呈现组，但该组不存在、重复定义或无法访问。
  • 直播目标时长小于实际允许的分片时长。
  • 媒体序号已递增，但旧的播放列表响应在缓存中保留过久。
  • Fragmented MP4 流遗漏或失去了对初始化映射文件的访问权限。
  • 密钥 URL 的有效期短于播放列表和分片 URL 的有效期。
  • 信号源切换改变了时间戳或编码参数，却未添加必需的 #EXT-X-DISCONTINUITY 断点。
  • 点播 (VOD) 播放列表因未正确声明结束标记而导致客户端持续轮询。

我们的 M3U8 清单检测器 可以提取并汇总播放列表类型、变体、编解码器、主机、密钥及警告信息。结合本参考手册解读这些检测结果，然后在 在线播放器 中测试具体的 URL。

相关指南与工具