深入解析 zyfun — 基于 Electron 构建的模块化流媒体与 IPTV 播放器

如果你曾经在桌面上尝试过设置 IPTV 或网络视频播放，很可能遇到过两个极端。一方面是像 Kodi 这样的臃肿一体化解决方案，它们需要数百兆的依赖项，复杂的界面让人望而却步。另一方面是简陋的工具，你只能手动将播放列表嵌入文本配置文件中，既没有像样的搜索功能，也没有同步功能。

最近我发现了 zyfun。它是备受欢迎的 ZY-Player 的直接继承者，完全使用现代技术栈重写。该项目在 GitHub 上已获得超过 8,800 颗星，但中国社区之外很少有人知道它。原因很简单：文档是中文的，机器翻译往往不够准确。然而，这个项目背后的工程设计值得深入研究。

技术架构解析

从架构上看，zyfun 是一个基于 Electron、Vue 3、Vite 和 TypeScript 构建的桌面应用程序。作者选择了 TDesign 作为界面的组件库。

该应用程序作为轻量级客户端运行。它不包含内置内容，而是作为外部源的处理程序。你向客户端提供一个结构化的 JSON 配置，应用程序负责数据解析、过滤、目录搜索和流播放。

关键工程决策

该项目的代码库包含几个有趣的技术方案，使其有别于典型的自建播放器。

1. 模块化源适配器

作者没有使用僵化的解析逻辑，而是实现了一套适配器系统（类型 T0 到 T4）。这有助于连接完全不同的后端：

• T0 和 T1：经典的 REST 接口，返回 XML 或 JSON 响应。
• T3 和 T4：脚本适配器，支持执行自定义处理器，包括 JavaScript（DRPy）、CatVod 和 Python。
• 通过 Alist 协议连接文件存储。

得益于此，你只需在配置文件中描述字段映射模式，就能添加新的电影网站或家庭 NAS 目录，无需重新构建二进制文件本身。

2. 通过 Chrome DevTools Protocol 进行流嗅探

许多在线影院将直接流链接隐藏在复杂的脚本后面。通常这类任务通过隐藏的 iframes 来解决，但这往往会破坏页面。

在 zyfun 中，流拦截是通过 CDP（Chrome DevTools Protocol）实现的。应用程序在隔离的 Chromium 上下文中打开目标 URL，订阅网络级事件 Network.requestWillBeSent，并捕获文件链接 .m3u8 或 .mp4。这种方法比启发式正则匹配更可靠。

3. 可切换的视频内核

在应用程序内部，没有硬绑定到单一播放器。你可以在设置中选择所需的引擎：

• XGPlayer（由字节跳动团队开发）
• ArtPlayer
• 通过系统调用调用外部二进制文件（例如 mpv 或带硬件解码的 VLC）

如果原生 Web 播放器无法处理高码率或特定编码，一键即可将流转发到外部 mpv。

4. 同步和内置 AI

观看历史、书签和源配置通过 WebDAV 或 iCloud 同步。如果你有多台设备使用这个应用，这将非常方便。

作者还添加了与 OpenAI API 的集成。客户端可以向选定的语言模型发送请求，快速获取简要剧情概要或类似作品的推荐。

日常使用方面的一个贴心设计是：设置中包含老板键功能。在 macOS 上默认按下热键（Shift+Cmd+Z）会立即将窗口隐藏到系统托盘并静音。

配置工作原理

所有源数据库都通过一个 JSON 文档导入。结构分为独立的块：用于点播目录的 site、用于播放列表的 iptv、用于单独流的 channel，以及用于链接解析器的 analyze。

以下是标准源描述的样子：

安装和平台支持

为 Windows（x64、arm64）、macOS（Intel 和 Apple Silicon）以及 Linux（AppImage、deb、rpm、AUR 包）提供了预构建包。

在 macOS 上安装时，系统可能会阻止运行未签名的应用程序。可以通过标准的 quarantine 属性重置来绕过：

在 Linux 上，某些发行版上运行 AppImage 时需要 libfuse2 库：

总结

zyfun 对于那些想要控制自己的媒体流而不被专有服务束缚的人来说，是一个可靠的选择。

这个项目适合哪些人：

• 需要干净播放器、支持电子节目单和便捷频道分组的 IPTV 爱好者。
• 希望将不同 API 整合到单一客户端的家庭媒体服务器所有者。
• 寻找 Chrome DevTools Protocol 集成实际案例的 Vue 和 Electron 开发者，用于后台网络流量分析。

源代码以 AGPL-3.0 许可证开源。如果你正在寻找一个功能全面的流媒体客户端，这个仓库绝对值得一看。