简介面向Web前端与全栈开发者这套H5 m3u8视频在线播放器完整源码重点解决m3u8/TS流在网页端跨浏览器播放难、原生video标签支持不统一等问题可直接用于项目快速集成或学习HLS播放原理。资源共19个文件以9个JavaScript脚本、4个CSS样式、1个HTML入口页面和1个PHP后端接口为主另含字体图标等静态资源压缩包仅622KB结构紧凑、便于直接部署或按需改造。当前已有54391人学习下载。源码支持通过URL参数传入m3u8地址即刻播放并兼容MP4等常见格式同时呈现了M3U8文件解析、HLS.js播放器集成、跨域请求处理、异常捕获等关键实现读者既能获得可直接运行的在线播放接口也能快速理解H5流媒体播放器的整体设计与部署要点尤其适合初次接触HLS协议与流媒体播放的开发者。1. 把 m3u8 直接塞进 video 标签之前先把这三个问题想清楚m3u8 在线播放器的开发量远比看起来大它不是一个地址交给 video 标签就能跑起来的玩具而是播放器内核、在线播放接口和源码侧的切片调度三部分协同的结果。隐藏的坑集中在三个方向一是 m3u8 本身是带版本、带分片时长、可能带加密标记的索引文件解析错一个标签就黑屏二是浏览器原生不认 HLS 协议必须借助 MSE 把 TS 分片喂给 video 元素三是播放接口如果只返回一个静态地址遇到多码率、防盗链或直播追帧场景会立刻露馅。这篇文章按「结构原理 → 前端播放器接入 → 后端接口编排 → 实战排错」的顺序把 m3u8 在线播放器和在线播放接口的完整源码拆开讲适合前后端开发、音视频链路维护和想做私有化播放方案的技术团队。想从能放就行升级到能上线的人可以直接按这里的代码和参数往下落地。2. m3u8 索引结构Master Playlist、Media Playlist 与 TS 分片2.1 m3u8 是什么UTF-8 编码的播放列表不是视频文件m3u8 是 HLS 协议中的播放列表文件文件本身是 UTF-8 编码的扩展 M3U 格式。它不包含一帧画面只负责描述视频资源在哪里、每个分片播多久、密钥从哪里取。在线播放器拿到 m3u8 后的第一件事不是解码画面而是先解析这个文本把分片地址整理成一个待下载队列。看一个最典型的单码率 m3u8 内容#EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:10 #EXT-X-MEDIA-SEQUENCE:0 #EXTINF:10.000, segment-0.ts #EXTINF:10.000, segment-1.ts #EXT-X-ENDLIST逻辑说明#EXTM3U声明这是扩展 M3U 文件#EXTINF后面跟的是分片时长和分片文件名#EXT-X-ENDLIST表示这是点播流而不是直播流。参数说明#EXT-X-TARGETDURATION是分片最大时长播放器用它预估缓冲窗口#EXTINF必须精确到毫秒否则跨播放器播放时可能出现音画不同步。很多新手把 m3u8 当作视频文件的指针认为拿到地址就能播。实际上播放器需要先请求 m3u8再逐个请求 TS 分片网络请求数量是分片数加一。一次完整的在线播放浏览器 DevTools 里能看到多串明显可分的请求瀑布这是 HLS 与 MP4 直播最直观的区别。2.2 主列表与媒体列表多码率切换的入口在哪一层正式的视频站不会直接给你一个包含 TS 分片的 m3u8而是先给一个主播放列表也就是 Master Playlist。它的作用是根据客户端带宽和设备分辨率从多个媒体播放列表里挑一条合适的流。#EXTM3U #EXT-X-STREAM-INF:BANDWIDTH1280000,RESOLUTION1280x720,CODECSavc1.4d401f,mp4a.40.2 720p/index.m3u8 #EXT-X-STREAM-INF:BANDWIDTH2560000,RESOLUTION1920x1080,CODECSavc1.4d4028,mp4a.40.2 1080p/index.m3u8逻辑说明这是主播放列表播放器会读取BANDWIDTH估算下行带宽读取RESOLUTION判断是否适配当前屏幕再决定请求720p/index.m3u8还是1080p/index.m3u8。参数说明BANDWIDTH单位是 bit/s只代表该流的峰值码率不代表实际平均码率CODECS是编解码器标识部分老设备不会播放列表里没有这个字段的内容。在 m3u8 在线播放器的接口设计里这个层级决定了在线播放接口应该返回什么。如果前端需要支持清晰度切换接口应该返回主播放列表内容而不是直接返回具体分辨率的媒体列表。如果前端只有一种清晰度可以直接返回媒体列表。区分这两者比多写一道转发逻辑重要得多。2.3 从 m3u8 到画面完整的拉流链路和常见的断点位置一次成功的在线播放完整链路是播放器请求主 m3u8 → 根据带宽选择媒体 m3u8 → 按EXTINF顺序请求 TS 分片 → 分片进入 MSE Buffer → video 元素解码渲染。这个链路里最容易出问题的断点有三个。第一个是 CORShls.js 在浏览器里发起的公网分片请求必须带正确的跨域头否则分片能下下来但喂不进 MSE。第二是分片地址解析m3u8 里写的分片名如果是相对路径播放器会按 m3u8 自身的 URL 做拼装改成在线播放接口中转后接口必须负责把相对路径转成可直连的绝对地址或者用透传方式保留原始路径结构。第三是#EXT-X-ENDLIST缺失直播流的 m3u8 会持续追加分片播放器会反复轮询同一地址获取新增分片如果接口做了缓存导致响应内容不变播放就会永远停在最后一秒。直播与点播在接口层就要分开处理。点播流可以放心交给 CDN 缓存直播流的 m3u8 则建议在响应头加Cache-Control: no-cache避免多级缓存让播放器拿到旧列表。这也是m3u8 在线播放接口与普通静态文件接口最大的设计差异。3. 前端在线播放器集成hls.js 对接 MSE 的最小可用代码3.1 播放器选型为什么不要继续用 videojs-contrib-hls浏览器原生 video 标签只对 Safari 的 HLS 有原生支持Chrome、Firefox、Edge 都必须通过 Media Source Extensions 把 TS 分片转为 MSE 可识别的数据流。由于 HLS 在桌面 Chrome 上并不被直接支持选播放器内核的核心标准就是它把 m3u8 转成 MSE 的能力强不强、维护是否活跃。技术选型上hls.js 是目前主流的选择videojs-contrib-hls 已经停止维护且内部依赖已经过时。video.js 本身可以作为外层 UI 框架存在但它的 HLS 支持最终还是要交给 hls.js 内核处理。如果你的项目里已经有 video.js 的皮肤和插件体系可以保留 video.js 作为容器把 hls.js 作为 source handler 接进去如果是从零做直接用 hls.js 挂在一个原生 video 元素上代码更少、可控性更强。用一张表把常见方案摆清楚方便直接选方案底层协议处理适用浏览器直播低延迟支持维护状态hls.js 原生 videohls.js 接管 m3u8 解析与 TS 拉取Chrome、Firefox、Edge、现代移动浏览器支持可调 buffer 参数活跃video.js videojs-contrib-hls依赖 hls.js 内核同 hls.js支持配置透传插件已停维原生 video Safari系统播放器直接处理仅 Safari / iOS WebView天然低延迟无额外依赖flv.js 方案只处理 FLV 封装不解析 m3u8依赖 MSE较低只适用于 http-flv 场景对于 m3u8 在线播放场景优先选第一行hls.js 加原生 video把在线播放接口返回的地址作为loadSource的入参。3.2 hls.js 接入 m3u8 的最简页面代码直接用原生 video 元素加 hls.js能在一个 HTML 文件里把完整播放链路跑通。这个代码可以直接作为在线播放器的播放端源码基础!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titlem3u8 在线播放器/title style video { width: 100%; max-width: 960px; display: block; margin: 0 auto; background: #000; } /style /head body video idplayer controls muted playsinline/video script srchttps://cdn.jsdelivr.net/npm/hls.js1.5.13/script script const video document.getElementById(player); const playlistUrl /api/m3u8?idvod-1024tokeneyJhbGciOiJIUzI1NiJ9.demo; if (Hls.isSupported()) { const hls new Hls({ maxBufferLength: 30, maxMaxBufferLength: 60, liveSyncDurationCount: 3, enableWorker: true }); hls.loadSource(playlistUrl); hls.attachMedia(video); hls.on(Hls.Events.MANIFEST_PARSED, () { video.play().catch(() console.warn(autoplay blocked, waiting user gesture)); }); hls.on(Hls.Events.ERROR, (event, data) { if (!data.fatal) return; switch (data.type) { case Hls.ErrorTypes.NETWORK_ERROR: hls.startLoad(); break; case Hls.ErrorTypes.MEDIA_ERROR: hls.recoverMediaError(); break; default: hls.destroy(); break; } }); } else if (video.canPlayType(application/vnd.apple.mpegurl)) { video.src playlistUrl; } /script /body /html逻辑说明Hls.isSupported()判断当前浏览器是否支持 MSEloadSource接收在线播放接口返回的 m3u8 地址attachMedia把 HLS 数据流绑定到 video 元素。MANIFEST_PARSED事件表示 m3u8 解析完成此时调用play()成功率最高。参数说明maxBufferLength控制点播场景的分片缓冲秒数设得越大播放越稳定但首屏越慢liveSyncDurationCount控制直播追帧的延迟档位默认值是 3 个分片enableWorker开启后由 Web Worker 做分片转封装避免阻塞主线程。错误处理分支里NETWORK_ERROR时直接startLoad()续拉MEDIA_ERROR时调用recoverMediaError()让播放器尝试恢复解码上下文。这里不推荐收到错误就立刻销毁实例因为大部分网络抖动是一次性的直接重连成本更低。3.3 video.js 做 UI 封装时的 m3u8 接入写法如果项目已经用了 video.js 的皮肤和插件生态不需要重写 UI只需要让 video.js 支持 m3u8 解析。video.js 8 以上版本可以直接配合 hls.js 使用方式是在播放器初始化后用 hls.js 接管媒体加载再通过videojs.registerPlugin封装成统一入口。import videojs from video.js; import Hls from hls.js; export function createM3u8Player(container, options) { const player videojs(container, { controls: true, autoplay: options.autoplay || false, fluid: true, sources: [] }); const hls Hls.isSupported() ? new Hls({ maxBufferLength: 30 }) : null; const loadM3u8 (url) { if (hls) { hls.loadSource(url); hls.attachMedia(player.tech().el()); } else if (player.tech().el().canPlayType(application/vnd.apple.mpegurl)) { player.src({ src: url, type: application/vnd.apple.mpegurl }); } }; player.loadM3u8 loadM3u8; return player; }逻辑说明hls.js 在 video.js 体系下不通过 source handler 注册而是直接把 hls 实例绑定到 video 底层元素。player.tech().el()能拿到 video.js 内部真实使用的 video 标签这是接入能否成功的关键。参数说明fluid: true让播放器尺寸跟随容器宽度等比变化options.autoplay是布尔值移动端浏览器通常会忽略自动播放需要用户手势触发。这样封装后页面里只需要player.loadM3u8(playlistUrl)一行就能完成在线播放器接入UI 交场逻辑和播放内核完全解耦。后续要接清晰度切换也只需要多次调用loadM3u8替换地址不需要改动 UI 层任何代码。3.4 直播与点播的配置差异同一个播放器两套 buffer 参数m3u8 在线播放接口返回的流可能是点播也可能是直播前端配置需要区分。点播场景的核心诉求是不要因为网络波动就卡顿可以适度把maxBufferLength调大到 30 到 60直播场景的核心诉求是延迟别太大应该把liveSyncDurationCount调低。直播参数建议是const hls new Hls({ liveSyncDurationCount: 2, liveMaxLatencyDurationCount: 6, maxBufferLength: 8, backBufferLength: 30 });逻辑说明直播流的延迟约等于缓冲分片数乘以分片时长。分片时长 4 秒时liveSyncDurationCount: 2意味着播放器会把播放点维持在列表末尾大约 8 秒的位置延迟可控。参数说明liveMaxLatencyDurationCount是延迟上限超限时播放器会自动跳到更靠近直播边缘的位置backBufferLength控制已经播放完的数据在内存里保留多久直播场景保留 30 秒就够点播场景建议保留更大以支持快速回拖。4. 后端在线播放接口签名鉴权、CORS 与 m3u8 地址分发4.1 在线播放接口的职责边界返回 m3u8 内容还是返回直链地址后端在线播放接口有两种实现思路。第一种是地址分发型接口只返回一个 m3u8 直链地址播放器自行去拉取。第二种是内容代理型接口读取源 m3u8 内容改写分片地址后把文本返回给前端。两种方式各有适用场景。地址分发型实现简单适合 m3u8 本身就是公网可访问地址的场景接口只需要做鉴权、防盗链和清晰度选择。内容代理型适合源 m3u8 只能从内网访问、或者分片地址已经过期需要动态签名的场景后端在返回前会把segment-0.ts这类相对路径改写成经过签名的时间戳地址。我一般会把两种方式封装在同一个接口里用参数redirect控制返回行为router.get(/api/m3u8, async (ctx) { const { id, quality, token, expire, redirect } ctx.query; const sourceUrl await resolveSourceUrl(id, quality); // 校验签名 const expect sign(id : quality : expire); if (token ! expect) { ctx.status 403; ctx.body { code: 403, message: token invalid }; return; } if (redirect yes) { ctx.redirect(sourceUrl); } else { const body await rewritePlaylist(sourceUrl); ctx.set(Content-Type, application/vnd.apple.mpegurl); ctx.body body; } });逻辑说明resolveSourceUrl负责把视频 ID 映射到真正的 m3u8 地址这个映射表通常存在数据库或配置中心。rewritePlaylist读取源 m3u8 内容把内部相对路径分片地址拼接成完整的、带签名参数的地址。参数说明quality用于选择清晰度服务端直接切换主播放列表redirectyes时接口返回 302由播放器直接拉源站适合源站无防盗链的场景。4.2 带过期时间的 HMAC 签名鉴权防止 m3u8 地址被到处转贴在线播放接口最大的风险是地址泄露后被全网转贴流量成本全算在自己头上。最常用的治理手段是 HMAC-SHA256 签名加过期时间。前端请求接口时带上expire时间戳和token后端用同样的密钥对关键参数计算签名再比对。const crypto require(crypto); const SECRET process.env.PLAY_SECRET || change-me-in-prod; function sign(id, expire) { const text ${id}:${expire}; return crypto.createHmac(sha256, SECRET).update(text).digest(hex); } // 校验中间件 async function auth(ctx, next) { const { id, expire, token } ctx.query; if (!id || !expire || !token) { ctx.status 400; ctx.body { code: 400, message: missing auth param }; return; } if (Number(expire) Date.now()) { ctx.status 401; ctx.body { code: 401, message: expired }; return; } if (sign(id, expire) ! token) { ctx.status 403; ctx.body { code: 403, message: sign invalid }; return; } await next(); }逻辑说明签名的内容是id:expireexpire用 Unix 毫秒时间戳表示。过期时间应该设置在 10 到 30 分钟太短会导致播放器在长视频播放中途签名失效太长则失去防盗链意义。参数说明expire由前端生成还是后端生成需要根据业务定如果前端不可信就改成前端传id后端自动生成过期时间并通过Set-Cookie或签名后的m3u8地址传回去。在 m3u8 场景中要注意播放器拉取 TS 分片时也会发起大量请求如果每个分片地址都带签名服务端验签 QPS 会很高。所以通常只对 m3u8 接口做签名校验TS 分片通过 Referer 校验或 CDN 上的 URL 鉴权保护不要把验签压力集中在一个接口上。4.3 CORS 跨域hls.js 拉流时最常见的失败原因hls.js 是 XHR 拉取 m3u8 和 TS 分片属于跨域请求浏览器会强制带上Origin头。服务端如果没返回正确的Access-Control-Allow-Origin播放器会出现能请求到内容但loadSource报错的情况而且这种报错在移动端上经常被忽略。一个能覆盖 m3u8 场景的 CORS 配置如下app.use(async (ctx, next) { const origin ctx.get(Origin) || ; if (origin) { ctx.set(Access-Control-Allow-Origin, origin); ctx.set(Access-Control-Allow-Credentials, false); ctx.set(Access-Control-Allow-Methods, GET, OPTIONS); ctx.set(Access-Control-Allow-Headers, Content-Type, Range); } if (ctx.method OPTIONS) { ctx.status 204; return; } await next(); });逻辑说明Access-Control-Allow-Methods只需要GET, OPTIONS因为 m3u8 在线播放接口只对外提供拉流能力。Access-Control-Allow-Headers里要带Range否则分片续传和拖拽播放的 Range 请求会被浏览器拦截。参数说明Access-Control-Allow-Credentials设为falseHLS 拉流通常不需要携带 Cookie带上反而会触发更严格的预检逻辑。生产环境下不建议把 CORS 写死在业务代码里用 Nginx 处理更干净location ~ \.(m3u8|ts)$ { add_header Access-Control-Allow-Origin *; add_header Access-Control-Allow-Methods GET, OPTIONS; add_header Access-Control-Allow-Headers Content-Type, Range; if ($request_method OPTIONS) { return 204; } proxy_pass http://media_backend; }注意Access-Control-Allow-Origin: *适用于公网公开视频如果分片涉及付费内容这个写法会彻底放开跨域截取应该只允许固定域名来源。4.4 服务端转发 m3u8 和分片解决相对路径与内网源访问问题源站的 m3u8 文件里经常写的是相对路径播放器拿到在线播放接口返回的内容后会基于接口地址去拼分片地址。一旦接口地址和真实媒体地址不在同一个域拼出来的分片地址就会 404。这时接口要做内容改写。async function rewritePlaylist(playlistUrl) { const text await fetchPlaylist(playlistUrl); const base new URL(playlistUrl); const lines text.split(\n); const rewritten lines.map((line) { const trimmed line.trim(); if (trimmed !trimmed.startsWith(#)) { return new URL(trimmed, base).toString(); } return line; }); return rewritten.join(\n); }逻辑说明new URL(trimmed, base)会把 m3u8 里的相对地址基于源 m3u8 地址解析成绝对地址。以#开头的行是协议标签原样保留。改写后的 m3u8 可以让播放器跨域拉取同名分片而不再依赖接口域的路径。参数说明如果源站分片也有防盗链这里改写时还要同时拼上签名查询参数例如new URL(trimmed, base) ?tokenxxx。服务端转发还有一个好处是兼容源站只允许内网访问的情况。在线播放接口所在的机器能访问内网源站但浏览器不能。此时接口把 m3u8 和 TS 分片全部代理出来浏览器只和接口域通信即可。5. 加密分片加载、直播延迟与播放器销毁的实战细节5.1 加密 m3u8EXT-X-KEY与 AES-128 分片解密部分付费视频的 m3u8 里会带着#EXT-X-KEY:METHODAES-128,URIkey.bin,IV0x...表示分片是 AES-128 加密的需要先获取密钥再解密分片。hls.js 会自动处理这个流程但密钥请求同样受 CORS 约束。密钥文件如果和 m3u8 不在一个域服务端必须给密钥文件也加上跨域头。另一个容易踩的坑是密钥地址在服务端改写时被忽略。很多接口对 m3u8 里的分片地址做了绝对化却忘了处理URIkey.bin里的相对路径结果播放器在拉密钥时 404。改写时要把URI后的内容也做 URL 拼接const rewritten line.replace(/URI?([^,])?/i, (match, p1) { if (p1.startsWith(http)) return match; return match.replace(p1, new URL(p1, base).toString()); });逻辑说明正则只匹配以URI开头的部分p1是原始密钥相对路径替换为绝对地址。参数说明如果密钥本身就是data:URI 或已经带域名需要跳过处理避免二次拼接。5.2 直播低延迟治理liveSyncDurationCount配合短分片切流在线播放接口如果是给直播用延迟主要来自三个地方切片时长、播放器缓冲、播放器追帧速度。切片时长由服务端决定播放器侧能改的是后两个。把liveSyncDurationCount从默认 3 降到 1播放器会在距离直播边缘更近的位置起播但网络波动时卡顿率会上升。部署时把分片时长和播放器参数配合调整更有效服务端多输出一条 2 秒分片时长的低延迟流播放器用liveSyncDurationCount: 2去拉总延迟能控制在 6 到 8 秒。如果业务要求再低单靠 HLS 很难需要切换到 HTTP-FLV 或 WebRTC 方案不在 m3u8 在线播放接口的讨论范围内。5.3 hls.destroy() 与内存回收单页应用里最容易漏掉的一行Vue 或 React 页面切换后如果只销毁 video 元素而没销毁 hls 实例播放器会继续拉取分片造成内存只升不降。在组件卸载时执行hls.destroy()同时把 video 的src清空是最基础也是最重要的内存治理手段onBeforeUnmount(() { if (hls) { hls.destroy(); hls null; } video.removeAttribute(src); video.load(); });逻辑说明hls.destroy()会停止所有正在进行的 XHR、清空 MSE Buffer、解除事件监听。video.load()让 video 元素重置内部状态避免黑屏画面残留。验证方法是在 DevTools 的 Performance 面板录制一次进页面播放 30 秒、离开页面 的操作看 JS Heap 曲线是否在下一次进入前恢复正常。如果曲线逐次走高说明有播放器实例没有被正确销毁。另一个验证在线播放接口是否健康的技巧是直接看响应头点播流应该能看到 CDN 命中的X-Cache标志直播流的 m3u8 响应头里Cache-Control应该为no-cache。结合curl -I /api/m3u8?idvod-1024返回的状态码和Content-Type: application/vnd.apple.mpegurl能快速定位是前端问题还是接口分发问题。本文还有配套的精品资源点击获取