LunaTV 直播：M3U 订阅一键变高清频道列表的完整实战指南
【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV
收藏夹里躺着一堆 M3U 订阅链接，想找个能稳定开播、还带节目单的播放器总是不得劲？LunaTV 的直播功能就是干这个的：把一条 M3U 订阅地址变成可分组、带节目单（EPG）的频道列表，在线直接看。这篇走一遍从部署到开播的完整路径，顺带讲讲里面几个容易忽略的机制和踩坑解法。
先把它跑起来：部署和添加 M3U 订阅的方法
LunaTV 仅支持 Docker（或基于 Docker 的平台）部署，按 README.md 里的 compose 配置拉起来即可，一行命令：
git clone https://gitcode.com/GitHub_Trending/lu/LunaTV有个心理预期要提前打好：部署完是个空壳，不内置任何直播源，订阅得自己收集。然后进入管理页的"直播源配置"，把下面四个字段填好，点"刷新直播源"，系统拉取频道列表并自动回填频道数：
| 字段 | 作用 | 填写建议 |
|---|---|---|
| M3U 订阅链接 | 频道列表的来源 | 支持 http/https 两种格式 |
| EPG 地址 | XMLTV 节目单 | M3U 头部带 x-tvg-url 时可留空，会自动识别 |
| User-Agent | 模拟播放器身份 | 部分源有防盗链校验，保持默认即可 |
| 频道数量 | 刷新后自动回填 | 显示 0 说明这次拉取失败 |
核心解析逻辑在 src/lib/live.ts：拉完 M3U 后解析频道与分组，再按 tvg-id 去匹配 EPG 里的节目。
开播体验：选源、分组浏览、节目单自动跟播
进入直播页，先选一个源，频道按 M3U 里的分组归类展示，点任意频道即播。下方有一条节目单滚动条，会自动滚到当前正在播出的节目位置，不用自己翻。
想换另一个源时，页面里有专门的直播源面板，列出每个源的名称和频道数，点一下就能整体切换，当前用的源会有标记（页面实现在 src/app/live/page.tsx）。
进阶：缓存、流式解析和换源三个隐藏能力
- 频道列表缓存：频道列表首次访问后被缓存，之后切换分组、刷新页面都是秒开，不会重复拉订阅。源变动后到管理页手动刷新即可，入口在 src/app/api/admin/live/route.ts。
- 节目单流式解析：EPG 的 XML 往往体积很大，LunaTV 采用逐行流式读取，只保留订阅里实际出现的 tvg-id 对应的节目，避免撑爆内存，接口实现在 src/app/api/live/epg/route.ts。
- 播放器换源：播放器基于 ArtPlayer 与 HLS.js，右侧面板列出各资源的带宽与延迟，哪个快切哪个。
播不出来？对照这三条排障
| 现象 | 原因 | 解法 |
|---|---|---|
| 频道列表为空 | 订阅源失效，或需要特定 UA | 换一个有效订阅，或调整 UA 后重新刷新 |
| 没有节目单 | EPG 地址填错，或 EPG 与 M3U 里的 tvg-id 对不上 | 核对两个文件里同一频道的 tvg-id 字段是否一致 |
| 部分频道无法播放 | 源本身失效，与 LunaTV 无关 | 换源，或把能用的收藏备用 |
一句话收尾：手头有 M3U 订阅、想要开箱即看直播的用户直接按上面的步骤走就行；下一步建议把常用频道加入收藏，切换起来更省事。
【免费下载链接】LunaTV本项目采用 CC BY-NC-SA 协议，禁止任何商业化行为，任何衍生项目必须保留本项目地址并以相同协议开源项目地址: https://gitcode.com/GitHub_Trending/lu/LunaTV
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
