HLS 流媒体加载失败的排查清单

现象

播放器就是不出声。控制台出现以下错误之一：

Error: HLS is not supported.
HLS Error: hls.js not found
[HLS.js] Error parsing M3U8 playlist
[HLS.js] Error while loading playlist

排查清单

1. hls.js 加载顺序对不对

hls.js 必须在 APlayer 之前加载：

<!-- ✅ 正确顺序 -->
<script src="hls.min.js"></script>
<script src="APlayer.min.js"></script>

<!-- ❌ 错误顺序 -->
<script src="APlayer.min.js"></script>
<script src="hls.min.js"></script>

APlayer 初始化时会检查 window.Hls 是否存在。如果 APlayer 加载时 hls.js 还没加载好，它就认为当前环境不支持 HLS。

2. type 参数有没有设置

使用 HLS 时必须在 audio 对象里声明 type: 'hls'：

// ✅ 正确
audio: [{
    name: '电台直播',
    url: 'your-live.m3u8',
    type: 'hls'    // ← 重要
}]

// ❌ 错误：不写 type
audio: [{
    name: '电台直播',
    url: 'your-live.m3u8'
    // type 默认 'auto' → APlayer 会直接给 audio.src 赋 m3u8
    // 只有 Safari 能原生播放 m3u8
}]

3. hls.js 版本问题

某些旧版本的 hls.js 和 APlayer 有兼容性问题。推荐用较新的稳定版本（1.5.x）：

<script src="hls.min.js"></script>

4. m3u8 文件本身有没有问题

直接在浏览器打开 m3u8 URL：

• 能显示文本内容（M3U8 的文本格式）——OK
• 404 —— URL 不对
• 下载一个文件（而不是显示）——Content-Type 头可能不对，应该是 application/vnd.apple.mpegurl 或 application/x-mpegURL

5. m3u8 里引用的 TS 分片

M3U8 文件里的 TS 分片路径必须正确。直接打开 M3U8 文件看看里面的分片 URL：

#EXTM3U
#EXTINF:10.0,
segment001.ts       ← 相对路径还是绝对路径？
#EXTINF:10.0,
segment002.ts
#EXTINF:10.0,
segment003.ts

如果是相对路径（segment001.ts），浏览器会以 m3u8 所在目录为基准解析。确认那个位置确实有 TS 文件。

6. CORS 跨域

m3u8 和 TS 分片都可能遇到跨域问题。参考 音频跨域问题 的排查步骤。

重点检查：

• m3u8 文件的响应头有没有 Access-Control-Allow-Origin
• TS 分片的响应头有没有同样的头
• 两者都要有——m3u8 只是索引，真正加载的是 TS 文件

7. TS 分片的编码格式

HLS 只是容器协议，里面装的还是浏览器能解码的音频。常见的编码：

如果你的 TS 分片用了浏览器不支持的编码，即使 HLS 层成功了，播放时也会报解码错误。

8. 自定义 customAudioType 里的错误

如果你用的是 customAudioType（而不是 type: 'hls'），检查：

customAudioType: {
    'myHls': function(audioElement, audio, player) {
        // 有没有检查 Hls.isSupported()？
        if (!Hls.isSupported()) {
            player.notice('HLS 不支持');
            return;
        }

        const hls = new Hls();
        hls.loadSource(audio.url);
        hls.attachMedia(audioElement);

        // 有没有处理错误事件？
        hls.on(Hls.Events.ERROR, function(event, data) {
            console.error('HLS Error:', data);
        });
    }
}

9. Safari 的特殊情况

Safari 原生支持 HLS——不需要 hls.js。如果你只面向 Safari 用户，直接用：

audio: [{
    name: '电台',
    url: 'live.m3u8'
    // 不写 type，Safari 原生就能播
}]

但如果你用了 type: 'hls' 但没有加载 hls.js，Safari 也会失败——因为 APlayer 会尝试找 window.Hls，找不到就报错。

快速定位流程

HLS 不能播
  ├─ 控制台看 Hls.isSupported() 结果
  │   ├─ 返回 false → 当前浏览器不支持，需要 hls.js
  │   └─ 返回 true → 继续排查
  ├─ 检查 type 是否为 'hls'（或自定义类型）
  ├─ 直接浏览器打开 m3u8 URL
  │   ├─ 404 → URL 问题
  │   └─ OK → 继续
  ├─ 检查 m3u8 里的 TS 分片路径
  ├─ 检查 CORS（Network 面板看 Response Headers）
  └─ 看 TS 分片编码