M3U8 常见错误及解决方案
使用这份指南排查 M3U8 播放、下载和转换失败。
快速诊断提示： 多数 M3U8 问题来自 CORS 策略、分片缺失、编码不兼容、网络超时或加密密钥不可访问。请先查看浏览器 Network 和 Console 面板。
CORS 跨域错误
错误信息
Access to XMLHttpRequest at 'https://example.com/video.m3u8'
from origin 'https://yoursite.com' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.解决方案
1. 配置服务器 CORS 头
为加载 M3U8 文件的域名添加 Access-Control-Allow-Origin。
2. 使用后端代理
当源站无法暴露浏览器 CORS 头时，通过自己的服务器获取播放列表。
3. 使用同源资源
尽量将页面、播放列表、分片和密钥放在同一源下。
404 文件未找到
错误信息
GET https://example.com/segment-1.ts 404 (Not Found)
Failed to fetch segment #1 of "https://example.com/playlist.m3u8"解决方案
1. 检查 URL 路径
确认 M3U8 文件中的 TS 或 fMP4 分片路径正确。
2. 验证文件存在
直接打开分片 URL，确认服务器返回媒体文件。
3. 检查基础 URL
相对分片路径必须基于真实播放列表位置解析。
解码或播放错误
错误信息
MEDIA_ERR_DECODE: The media resource indicated by the src attribute
or assigned media provider object was not suitable.
DOMException: Failed to decode media resource解决方案
1. 检查编码格式
使用浏览器兼容的编码，例如 H.264 视频和 AAC 音频。
2. 验证 M3U8 语法
确认 #EXTM3U、#EXTINF 等必要标签存在且有效。
3. 使用 HLS 播放器
使用 HLS.js 或专用播放器提升浏览器兼容性。
网络超时或连接错误
错误信息
NetworkError: Failed to fetch
ERR_CONNECTION_TIMED_OUT
Manifest request timed out解决方案
1. 增加超时时间
给慢速网络更多时间，再判定播放列表或分片失败。
2. 使用 CDN 分发
通过 CDN 提供分片，降低全球访问延迟和丢包。
3. 添加重试机制
在播放失败前重试临时的播放列表、分片和密钥请求。
加密内容错误
错误信息
KEY_LOAD_ERROR: Failed to load decryption key
KEY_SESSION_ERROR: Failed to generate license request
DECRYPT_ERROR: Failed to decrypt segment解决方案
1. 验证密钥 URL
确保 #EXT-X-KEY 中的 URI 可访问，并返回预期密钥。
2. 检查密钥格式
AES-128 密钥应为 16 字节，避免被文本编码破坏。
3. 为密钥配置 CORS
密钥服务器必须允许播放页面从浏览器请求密钥。
推荐调试工具
浏览器开发者工具
检查 Network 请求、响应头、状态码和 Console 错误。
HLS.js Demo
在已知 HLS 播放器中测试直接 M3U8 URL，排除播放器问题。
FFmpeg/FFprobe
检查编码、流元数据、分片可用性和容器细节。
在线 M3U8 验证器
根据常见 HLS 要求验证播放列表语法。
常用调试命令
检查视频编码信息
ffprobe -v quiet -print_format json -show_streams video.m3u8测试 M3U8 URL 可访问性
curl -I https://example.com/video.m3u8下载并合并 M3U8
ffmpeg -i "https://example.com/video.m3u8" -c copy output.mp4