hls.js 入门教程与示例

2026-07-038 min read

什么是 hls.js？

hls.js 是在缺乏原生支持的浏览器中播放 HLS 的开源 JavaScript 库。它解析 M3U8、下载片段、处理 ABR 与 AES-128，并通过媒体源扩展（MSE）把数据喂给 HTML5 <video>。

Safari 可原生播 HLS；其他浏览器以 hls.js 为标准方案。概念背景：HTML5 M3U8 播放器内部。

安装

npm install hls.js

// CDN
// <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>

最小可运行示例

import Hls from "hls.js";

const video = document.getElementById("video");
const url = "https://example.com/stream.m3u8";

if (Hls.isSupported()) {
  const hls = new Hls();
  hls.loadSource(url);
  hls.attachMedia(video);
  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    video.play();
  });
} else if (video.canPlayType("application/vnd.apple.mpegurl")) {
  // Safari 原生 HLS
  video.src = url;
}

有用配置项

选项	默认	含义
`maxBufferLength`	30	目标缓冲秒数
`startLevel`	-1	起始画质（-1=自动）
`capLevelToPlayerSize`	false	画质上限对齐元素尺寸
`debug`	false	详细日志

核心事件

hls.on(Hls.Events.MANIFEST_PARSED, () => { /* 档位就绪 */ });
hls.on(Hls.Events.LEVEL_SWITCHED, (_, data) => {
  console.log("level", data.level);
});
hls.on(Hls.Events.ERROR, (_, data) => {
  if (data.fatal) {
    // 恢复或销毁 — 见排查指南
  }
});

调试帮助：hls.js 无法工作。

下一步

添加画质 UI 与统计，或跟随用 JS 自建 M3U8 播放器。不想写代码可先用我们免费的在线播放器试流。

常见问题解答

hls.js 在 Safari 能用吗？
Safari 上通常改用原生 HLS。

hls.js 免费吗？
是，开源。

需要后端吗？
不需要——只要有可访问的 M3U8 URL。

为什么需要 MSE？
它让 JavaScript 能把媒体片段追加到 video 元素。