把 Kodi 接上 IPTV 直播：pvr.iptvsimple 落地实操手册
2026/8/23 23:56:43
把 Kodi 接上 IPTV 直播：pvr.iptvsimple 落地实操手册
【免费下载链接】pvr.iptvsimpleIPTV Simple client for Kodi PVR项目地址: https://gitcode.com/gh_mirrors/pv/pvr.iptvsimple
pvr.iptvsimple 是一个开源 PVR 插件，负责把 M3U 频道列表和 XMLTV 节目指南接进 Kodi，让你在 Kodi 里直接收看 IPTV 直播。本文面向想自建频道、又不想写代码的家庭用户，覆盖从安装插件、录入第一个播放源，到整理频道分组、打开直播回看的完整流程。
跑起来之前 📋
| 项目 | 最低要求 | 缺了会怎样 |
|---|---|---|
| Kodi | 20（Nexus）及以上，推荐 21（Piers） | PVR 客户端列表里看不到 IPTV Simple 选项，装都装不上 |
| inputstream.ffmpegdirect | 与 Kodi 同版本 | 直播只能看不能暂停，时移回看功能整个不可用 |
| 网络 | 能访问 M3U 与节目指南地址 | 频道列表空白，TV 菜单卡在加载状态 |
| 磁盘 | 剩余几十 MB 即可 | 时移缓冲写满后暂停失效、画面卡住 |
装插件本身没有门槛：插件 → 插件浏览器 → 从库安装 → PVR 客户端，找到 "IPTV Simple Client" 装上，然后到 系统设置 → PVR 客户端 里把它启用。装完先别急着配，确认 TV 入口里出现了一个空的频道列表，说明 PVR 后端已经接上了。
主流程 📺
接入第一个 M3U 播放列表
操作路径：插件 → 设置 → 选择 IPTV Simple Client → 常规 标签页。
关键配置：把 M3U 文件位置填成远程地址或本机路径。新手建议先用本地文件跑通：
#EXTM3U #EXTINF:0 tvg-id="cctv1" group-title="新闻",CCTV-1 http://192.168.1.10:8080/live/cctv1.ts #EXTINF:0 tvg-id="hunan" group-title="综艺",湖南卫视 http://192.168.1.10:8080/live/hunan.ts验证信号：打开 Kodi 主界面的 TV → 频道，能看到上面两个频道名，点进去能出声出画面，即成功。tvg-id 字段决定这个频道能否匹配到节目单，建议认真填写。
为 Kodi IPTV 配置 XMLTV 节目单
操作路径：插件设置 → EPG 标签页。
关键配置：把 XMLTV 文件位置指向你的节目指南文件，支持 .xml、.gz（Gzip）和 .xz（XZ）三种压缩格式。两个参数建议核对一遍：
EPG 时间偏移（小时）：0 忽略 EPG 频道 ID 大小写：开时间偏移在默认 0 的情况下，指南时间戳和 Kodi 本机时间要有时差才需要改；大小写开关默认就是开的，一般不用动。
验证信号：选中任意频道，TV 信息栏显示"当前节目 + 起止时间"，节目指南页里该频道有一串节目条目。若某些频道显示"无数据"，是那些频道的 tvg-id 没匹配上，见后文踩坑部分。
用频道分组整理电视列表
操作路径：插件设置 → 组 标签页。
关键配置：模式有三档。默认是"全部频道"，即列表里出现所有组；第二档"指定频道组"适合列表特别长、只想留几类的情况；第三档"自定义频道组"读一个 XML 文件，分组完全由你定义。文件放在插件数据目录下的 channelGroups 子目录，插件已预置一个示例文件，改完文件名或直接用示例文件填内容即可：
<channelGroups> <group name="我的新闻"> <channel id="cctv1" /> <channel id="cctv13" /> </group> </channelGroups>验证信号：切到"自定义频道组"模式后，TV 频道列表只出现"我的新闻"一个组，组内是刚才列出的两个频道。
打开直播暂停与时移回看
操作路径：插件设置 → 时移 标签页。
关键配置：把"启用时移"打开，HTTP 和 UDP 两类源默认都允许。这一步依赖前文提到的 inputstream.ffmpegdirect：对 HTTP/UDP 源，它会默认启用时移模式，从你按下播放的那一刻开始缓冲。
验证信号：正在播放的频道按暂停，画面定格；按快进能回到刚才看过的片段。如果暂停后直接退出播放，说明时移没生效，按下面踩坑第 4 条处理。
把体验再拧一格 🎚
频道台标。默认状态：台标只来自 M3U 里的 tvg-logo，列表里很多频道是纯色块。建议值：在 台标 标签页填一个台标图片库的根地址（本地目录或远程 URL），来源优先级选"优先使用节目指南里的台标"。改完的变化：M3U 没给图、但 XMLTV 里带图的频道，列表里也会显示台标。
节目类型颜色。默认状态：所有节目类型都是同一颜色，扫一眼指南分不清电影和新闻。建议值：在 节目类型 标签页指向一个 genres.xml 映射文件，给常用类型配上颜色。改完的变化：节目指南里"电影""体育"等类型名变成对应颜色，扫列表时定位节目更快。
列表自动刷新。默认状态：禁用，M3U 文件变更后要重启 Kodi 才生效。建议值：刷新模式选"每天一次"，放在凌晨。改完的变化：上游改了频道或加台，第二天打开 TV 菜单自动就是新列表，不用手动碰。
踩坑速查 ⚠️
症状：TV 菜单空白，连频道都没有。根因：M3U 文件没下载下来，或者文件根本不是合法 M3U（缺 #EXTM3U 头）。 动作：插件设置 → 常规 标签页，把文件位置临时改成本机放好的文件确认能出频道，再换回网络地址；换回后仍空白，就用浏览器直接打开那个 URL，打不开就是上游的问题。
症状：部分频道没有节目单信息。根因：M3U 的 tvg-id 和 XMLTV 里的频道 ID 对不上，最常见的是大小写不一致。 动作：插件设置 → EPG 标签页，确认"忽略 EPG 频道 ID 大小写"处于开启状态（默认开）；仍不行的话，用文本编辑器对比两边的 ID 拼写，把 M3U 里的 tvg-id 改成和节目指南一致。
症状：节目单时间整体偏移固定几个小时。根因：节目指南源时区和 Kodi 本机时区不一致。 动作：插件设置 → EPG 标签页，把"EPG 时间偏移（小时）"改成 -8 或 +8 这类整点值，重新选台看当前节目时间是否和本地时钟对得上。
症状：直播无法暂停，或按暂停后画面退出。根因：inputstream.ffmpegdirect 没装；或者该频道是多播流，不走时移模式。 动作：先装 inputstream.ffmpegdirect 并重启 Kodi；若确认是组播地址（udp:// 开头），到插件设置 → 高级 标签页打开"转换多播流 URL"，按提示配好 udpxy 中继地址再试。
往后走
源码构建需要一份 Kodi 源码树，把插件克隆到与之平级的目录即可：
git clone https://gitcode.com/gh_mirrors/pv/pvr.iptvsimple cd pvr.iptvsimple && mkdir build && cd build cmake -DADDONS_TO_BUILD=pvr.iptvsimple -DADDON_SRC_PREFIX=../.. ../../xbmc/cmake/addons && make版本上注意：Kodi 20（Nexus）对应插件 v21.x，Kodi 21（Piers）对应 v22.x，两者都支持多实例配置，即添加多组 M3U/XMLTV 对来管理不同来源。想再深入，可以去 Kodi 官方论坛搜 "IPTV Simple" 版块，catchup 回放、请求头定制这类进阶配置都有现成讨论。
到这里，你已经有自己的直播频道、节目单和暂停回看了。插件更新比较频繁，定期在插件仓库查看更新；遇到异常，先确认 M3U 源本身还能用，再排查插件设置。
【免费下载链接】pvr.iptvsimpleIPTV Simple client for Kodi PVR项目地址: https://gitcode.com/gh_mirrors/pv/pvr.iptvsimple
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考