iptv-org/epg：用 Node.js 批量抓取电视节目单的实用工具

节目单缺失是 IPTV 的常见痛点

很多自建 IPTV 服务的用户会遇到同一个问题：频道能看，但电子节目指南（EPG）是空的。电视播放器没有节目信息，用户不知道现在播什么，也无法预约录制。iptv-org/epg 正是为了解决这个问题而存在。它提供一组工具，从数百个来源抓取数千个频道的节目数据，最终生成 XMLTV 格式的 guide.xml 文件。这个文件可以被 Kodi、Jellyfin、TiviMate 等播放器识别。项目的目标用户很明确：自己维护 IPTV 播放列表的人，以及需要为多个频道批量生成节目单的小型服务。它不是给普通观众用的，而是给愿意动手配置脚本和调度任务的用户准备的。

抓取流程：从站点到 XMLTV 文件

工具的核心逻辑是抓取。每个支持的站点在 sites 目录下有一个抓取脚本，脚本定义了如何从该站点的页面或接口提取频道 ID 和节目时间。运行 npm run grab 时，工具会读取这些脚本，按站点逐个请求数据，然后汇总输出为 XMLTV 格式。README 里给出了一个具体例子：npm run grab --- --sites=example.com。命令执行后，当前目录会出现 guide.xml。抓取是按频道逐个进行的，默认并发数为 1，也就是一个请求完成才发起下一个。这种保守设计是为了避免给目标站点造成压力，但也意味着抓取大量频道会非常慢。你可以通过 --maxConnections 提高并发，但文档明确警告：高负载下某些站点可能返回错误或完全屏蔽你的访问。这是抓取类工具的通病，iptv-org/epg 没有回避这个风险，而是把它写在了文档里。

安装与基本用法：三条命令起步

安装过程是标准的 Node.js 项目流程。首先确保系统有 Node.js 和 Git，然后克隆仓库：git clone --depth 1 -b master https://github.com/iptv-org/epg.git。进入目录后执行 npm install 安装依赖。抓取时，先从 SITES.md 文件里选一个支持的站点名，再运行 npm run grab --- --sites=example.com。注意命令里的三个横线，这是 npm 传递参数给脚本的写法，漏掉会报错。输出文件默认是 guide.xml，可以用 -o 参数改路径。如果要同时抓多个站点，用逗号分隔站点名，例如 --sites=example1.com,example2.com。更灵活的方式是使用 --channels 参数指定一个自定义的 channels.xml 文件，文件里可以只包含你需要的频道条目，格式如 <channel site="arirang.com" lang="en" xmltv_id="ArirangTV.kr" site_id="CH_K">Arirang TV</channel>。这样能避免抓取无关频道，节省时间和带宽。

定时抓取与 Docker 部署

节目单需要定期更新，iptv-org/epg 提供了两种方式。第一种是用 cron 或任务调度器，README 推荐了一个叫 chronos 的工具，命令是 npx chronos --execute="npm run grab --- --sites=example.com" --pattern="0 0,12 * * *" --log。这个命令会在每天 0 点和 12 点执行抓取。第二种是直接用 Docker 镜像，镜像地址是 ghcr.io/iptv-org/epg:master。运行 docker run -p 3000:3000 -v /path/to/channels.xml:/epg/public/channels.xml ghcr.io/iptv-org/epg:master 后，容器默认每天 00:00 UTC 抓取一次，生成的 guide.xml 通过 HTTP 服务暴露在 localhost:3000。Docker 方式的好处是环境隔离，不需要在宿主机装 Node.js。坏处是镜像体积大，而且每次配置变更都要重新创建容器。环境变量提供了细粒度控制，比如 CRON_SCHEDULE 可以改抓取频率，MAX_CONNECTIONS 控制并发，GZIP 和 JSON 分别决定是否生成压缩版和 JSON 版节目单。

并发与代理：性能调优的边界

工具提供了几个影响抓取速度和稳定性的参数。--maxConnections 默认是 1，意味着串行请求。提高到 10 会明显加快速度，但文档明确提醒：有些站点在重负载下会报错甚至封禁 IP。这是抓取工具固有的风险，iptv-org/epg 没有做任何规避，比如自动降速或重试机制。另一个参数是 --timeout，默认 30000 毫秒，超过这个时间请求会被放弃。--delay 可以设置请求间隔，但 README 中这个参数的说明被截断了，具体单位没有写全。对需要隐藏出口 IP 的用户，Docker 环境变量 PROXY 支持指定代理，例如 socks5://127.0.0.1:1234。这个功能对抓取某些地理限制的站点有用，但代理的稳定性会直接影响抓取成功率。整体来看，性能调优的余地是有的，但每个参数都伴随着站点被封的风险，需要用户自己权衡。

局限性与失败模式

这个工具最大的局限在于依赖第三方站点的结构。每个站点的抓取脚本是手工编写的，站点改版、接口变动、反爬机制升级都会导致脚本失效。README 没有提供任何监控或告警机制，你只能靠定时任务失败后的日志来发现问题。另一个问题是抓取速度。默认串行抓取，一个频道一个请求，如果目标站点响应慢，抓取几百个频道可能要几个小时。提高并发又会引来封禁风险。此外，输出格式只有 XMLTV，虽然这是通用标准，但如果你需要 JSON 格式，必须通过 Docker 的 JSON 环境变量开启，而且生成的 JSON 结构是否适合你的播放器，文档没有详细说明。还有一个容易忽略的点：工具本身不包含任何频道元数据，比如台标、频道分类，这些都需要从 iptv-org 的其他项目获取。如果你只想抓取一两个频道的节目单，用这个工具反而显得笨重，不如直接找现成的 XMLTV 文件。

替代方案：XMLTV 直接获取与专用 EPG 服务

如果你不想自己抓取，最直接的替代是使用现成的 XMLTV 文件。很多网站提供每日更新的节目单，格式已经是 XMLTV，下载后直接给播放器用即可。这种方式省去了抓取和解析的麻烦，但缺点是来源单一，覆盖的频道有限，而且这些文件的稳定性和时效性无法保证。另一个替代方案是使用专门的 EPG 服务，比如某些 IPTV 订阅服务会附带节目单，或者使用像 EPG.best 这样的聚合 API。这些服务通常提供 API 接口，按频道或按日期返回 JSON 或 XML，适合需要实时数据的应用。与 iptv-org/epg 相比，这些服务是托管式的，你不需要维护抓取脚本，但需要付费或者接受 API 限制。iptv-org/epg 的优势在于完全免费、开源、可自定义，但代价是你得自己处理所有维护工作。

维护成本与许可证

iptv-org/epg 的许可证是 Unlicense，这意味着代码被捐赠到公有领域，你可以自由使用、修改、分发，甚至不需要保留版权声明。但这也意味着没有任何担保，项目不承诺对任何损害负责。从维护角度看，项目本身是 iptv-org 组织下的一个活跃仓库，但最近没有发布正式版本，更新主要靠 git pull 拉取主分支。由于依赖 Node.js 生态，npm install 每次更新后都要重新执行，依赖冲突是潜在风险。更关键的是，站点抓取脚本的维护是持续性的工作。你依赖的某个站点可能几个月都没人更新脚本，一旦站点改版，你的定时任务就会静默失败。如果你没有能力自己修改抓取脚本，那么项目的维护节奏就决定了你的节目单质量。在采用前，建议检查 SITES.md 里你需要的站点是否在最近三个月内有更新记录，这能侧面反映维护活跃度。

编辑结论

iptv-org/epg 适合那些需要为自建 IPTV 服务生成节目指南的个人或小型团队，尤其是已经熟悉 iptv-org 生态、愿意用 Node.js 命令行工具的用户。它不适合对节目数据实时性要求极高、或者需要稳定商业级 SLA 的场景，因为抓取依赖第三方站点的页面结构，站点改版可能导致解析失败。在采用前，先确认你需要的频道是否在 SITES.md 中有覆盖，并检查对应站点的抓取脚本是否仍在维护。另外要注意 Unlicense 许可证意味着代码进入公有领域，你可以自由使用，但这也意味着项目不提供任何担保，出了问题只能自己解决。如果你只需要单一来源的 EPG，直接使用 XMLTV 格式的现成文件可能比维护这套工具更省事。

官方来源

1. Official documentation
2. Official README
3. Project repository