TVBox EPG节目单怎么配：xmltv地址、tvg-id匹配与直播无节目表排查（FongMi，2026）

redpear

简介

百度/必应/Google 对「tvbox epg」「tvbox epg接口」「tvbox epg地址如何配置」的联想非常整齐，说明用户已经会导入直播列表，却卡在 节目单（EPG）不显示、对不上、全是未知节目。

站内已有：

· 直播源总览（tid=33101）；
· m3u/txt 导入专帖（tid=33480）。

本帖 只深挖 EPG：字段从哪来、怎么匹配频道、时区与常见失败。不提供侵权直播源。


▲ TVBox / FongMi 直播 EPG 节目单对照（本地渲染）

一、EPG 在配置里的位置

据 影视TV 配置字典：

· Live 对象可带 epg 字段：节目表位置，逗号分隔；支持 XMLTV 与 API 模板；
· M3U 头可写 url-tvg="https://example.com/epg.xml"；
· 单频道可覆盖：Channel.epg、Channel.tvgId、Channel.tvgName；
· 还可配置 timeZone 等与时间显示相关的项（详见字典原文）。

也就是说：EPG 不是「再装一个 EPG App」，而是 直播配置的数据字段。

二、最小可用思路（合规）

· 先有一份 可播放的合法直播列表（自建 IPTV、运营商正版、自有局域网流转码等）；
· 准备一份与之匹配的 XMLTV（或壳支持的 EPG API 模板）；
· 在 Live 配置写：
   · "epg": "https://nas.lan/epg.xml"  
     或多个："epg": "https://a/epg.xml,https://b/epg.xml"；
· 刷新直播配置后，在频道列表/播放页查看节目信息。

M3U 示例头（示意）：

2. #EXTM3U url-tvg="https://nas.lan/epg.xml"
3. #EXTINF:-1 tvg-id="CCTV1" tvg-name="CCTV1" tvg-logo="...",中央台综合
4. http://127.0.0.1/play/1

复制代码

tvg-id / tvg-name 必须能在 XMLTV 的 channel id / display-name 侧匹配上。

三、匹配失败的典型原因

· 现象：完全无节目表｜原因：epg URL 404、未刷新｜处理：浏览器先下载 XML 看是否有内容
· 现象：只有一半频道有｜原因：tvg-id 不一致｜处理：统一 id，或用 Channel.tvgId 覆盖
· 现象：节目错位几小时｜原因：时区 timeZone / XML 时间基不一致｜处理：统一到本地时区策略
· 现象：昨天还有今天没了｜原因：EPG 源只给短窗口｜处理：换更新更勤的 XMLTV 生成器
· 现象：直播能播但 EPG 转圈｜原因：EPG 文件过大/服务器慢｜处理：裁剪频道、本地缓存到 NAS
四、和「仓库服务器」一起用

若你按仓库服务器帖托管 NAS：

2. tvbox-public/
3.   depot.json
4.   vod.json
5.   live.json      ← lives 里写 epg
6.   epg.xml

复制代码

epg.xml 用相对或绝对 URL 指到同一静态站，电视端只维护一个入口，EPG 更新可脚本化（例如定时生成 XMLTV）。公网分享 EPG 时注意 不要夹带未授权频道元数据。

五、操作步骤（FongMi 思路）

· 确认直播配置已成功加载（频道列表有台）；
· 编辑 Live：填 epg 或保证 M3U 含 url-tvg；
· 为关键频道补齐 tvg-id；
· 设置里刷新直播 / 清直播缓存后再看；
· 仍无数据时，用手机打开 epg URL，确认不是网关劫持页。

六、不要做什么

· 不要为了「全中国节目单」去下捆绑恶意插件；
· 不要把 EPG 失败当成播放器坏了就乱换破解盒；
· 不要在帖外求盗版「全球直播+EPG 合集」——法律与信任风险都高。

七、FAQ

Q1：只有点播要 EPG 吗？  
A：EPG 主要服务直播。点播用详情/更新时间，不走 XMLTV。

Q2：epg 能填多个吗？  
A：字典写明可逗号分隔多个位置。

Q3：和弹幕/字幕有关吗？  
A：无关。弹幕见 tid=33408，字幕见 tid=33409。

Q4：经典 TVBox 壳字段名不同？  
A：许多壳同样认 M3U 的 tvg-* 与 url-tvg；JSON 字段名可能是 epg 或嵌在 live 节点，以该壳文档为准。

Q5：EPG 很慢要加大缓冲吗？  
A：缓冲时间影响点播播放器；EPG 是额外 HTTP 拉取。应优化 EPG 文件大小与 CDN，而不是拉满点播缓冲。

Q6：节目名称乱码？  
A：XML 声明与实际编码不一致时常见，统一 UTF-8。

十、和缓冲、仓库帖的配合

EPG 不显示时，优先查 URL 与 tvg-id，而不是去调点播「缓冲时间」。仓库服务器场景下，把 epg.xml 与 live 列表放在同一静态目录，用绝对 URL 写进 epg 字段，可减少相对路径半对半错的问题。家人反馈「节目名怪」时，先问是哪个频道、哪个整点，再对照 XML 里该时段的 title，比盲目换播放器快得多。

总结

TVBox EPG 配置的核心是：合法直播列表 + 可访问的节目表 + tvg-id/name 匹配 + 时区一致。先让列表能播，再让节目单对得上；把 EPG 放到 NAS 与仓库服务器同目录维护，体验会稳定得多。空壳播放器不自带直播与节目单，请合规自备。

八、自建 XMLTV 的注意点（概念级）

如果你用脚本从合法数据源生成 XMLTV：

· 保持 channel id 稳定，不要每天换 id；
· programme 的 start/stop 使用文档约定的时间格式，并与 timeZone 策略一致；
· 文件太大时按分组拆分，利用 epg 逗号分隔加载；
· 生成后先用 XML 校验，再给电视用；
· 更新频率按节目单变化来，不必每分钟刷新，徒增 NAS 与电视负担。

客厅体验上，EPG 的价值是「现在播什么 / 下一档是什么」。若你的列表只有几十个自建频道，完全可以手写精简 XMLTV，反而比庞大的第三方节目单更干净。

把 EPG 与直播列表的版本号写进文件名或 notice 字段，家人反馈「节目不对」时，你能立刻知道他们是否还在用旧地址。配合仓库服务器帖，EPG 只是多一个静态文件，却能显著减少「这是什么台」的灵魂拷问。

合规再次强调：节目元数据同样可能涉及未授权整合，只处理你有权使用的频道信息。

九、验收清单（打勾再用）

· 直播列表本身可播放至少两个频道；
· 浏览器能下载 EPG 文件且体积合理；
· 抽样频道的 tvg-id 能在 XML 中搜到；
· 当前时段 programme 覆盖「现在」；
· 电视刷新后节目名与官方节目表（若你有正版对照）大致一致；
· 夏令时/时区变更后重新检查一次。

完成以上六步，EPG 就算真正「配好了」。若只完成第 1 步就抱怨没节目单，问题多半在匹配与时区，而不是播放器内核。把清单打印贴在 NAS 侧，后续每次改列表都跑一遍，可避免「改了直播却忘了改 EPG」的回归缺陷。对多地区家人共用时，更要固定一份时区策略，否则有人觉得节目「提前了两小时」，有人觉得「晚了」。

若频道很多，可先只给常看的十几个台写齐 tvg-id，其余以后再补；完美主义会让 EPG 工程永远做不完。先保证「常用台有节目名」，体验就会上一个台阶。

配置完成后，建议隔天再抽查一次「当前节目」是否仍更新，确认定时任务或手动更新 EPG 的流程可靠。