M3U8 常見錯誤及解決方案
使用這份指南排查 M3U8 播放、下載和轉換失敗。
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