TVBox 二次开发项目盘点：GitHub 上的三类分支与主力仓库

TVBox 的官方仓库在 2022 年 7 月就已经封仓停更，所以严格来说，今天你在电视盒子上装的每一个 TVBox、每一份「影视仓同款」，都是别人二次开发的产物。但「二次开发」这四个字底下藏着三种完全不同的技术路线：有的人在原码上改 UI，有的人一行原码都没碰、自己重写了一个壳，还有的人干脆不碰 App，只在服务端做接口。分不清这三类，看 GitHub 就会一片混乱——高星仓库里一半根本不是播放器，而是配置源。

这篇按「代码关系」而不是「版本名字」来分，把三类路线各自的代表仓库、技术栈、维护状态和真正该动手的地方讲清楚。看完你应该能判断：想改成什么样，该 fork 哪个仓库。

一、三类二次开发，先分清

判断一个仓库属于哪一类，其实不用读代码，看三件事就够了：它是不是官方仓库的 fork、用什么语言写、以及它到底读不读 TVBox 那份 JSON 配置。

这三类的分野在现实里非常明显。第一类的仓库打开来，目录结构、包名、混淆方式几乎一模一样，改起来像在维护一份 2022 年的老项目；第二类打开是干净的现代 Android 工程，甚至压根不是 Android；第三类根本没有 APK，只有 Docker 镜像和配置文件。

二、第一类：同一个源码底座，改 UI 与内核

所有这类项目的祖先都是 CatVodTVOfficial/TVBoxOSC——猫影视作者停更后公开的那份源码。它在 2022 年 7 月封仓，如今仓库本身也已经 404：源码被人独立重传成 j4Uq/TVBoxOSC（约 18k 星），各条分支也一直在接续修改。本节讲的就是这几条线。全部 46 个仓库的清单在这里。

2.1Q 版与 T 版：两条最粗的分支

Q 版（q215613905/TVBoxOS）是兼容性最好的一条，Android 4.x 的老盒子基本只能靠它。它的定位是「稳」：UI 朴素、改动克制、直播回放这类功能做得早。想给长辈的老盒子续命，或者你的设备 API 等级很低，就从这里 fork。

T 版（takagen99/Box，约 3.1k 星）是 Q 版之后 UI 改得最狠的一支，蓝黑配色、分辨率与网速屏显、中英双语、长按影片聚合搜索。它本身是官方仓库的 fork，代码结构相对清晰，是这三条线里最适合拿来做二次开发的起点：UI 层和业务层分得比较开，换一套配色或重排首页不用动播放逻辑。代价是它 2026 年 2 月之后基本停更了，上游的播放器内核修复拿不到。

2.2打包版：不写代码，只负责出 APK

o0HalfLife0o/TVBoxOSC 严格说不算「开发」，它是把 Q 版和 T 版编译成 APK 的发布仓库。但它对理解整个生态很关键：社区里流传的绝大多数「TVBox 官方版 APK」都是从这里出的，因为它把两套源码的构建流程自动化了。你要自己出包，可以直接抄它的 GitHub Actions 配置，省掉配 Gradle 和签名的一堆坑。

2.3几条窄而实用的分支

这一类的共同特征是：上手极快，天花板也低。原码是 2022 年的 Java + 老版 ExoPlayer/IJK，包结构层层嵌套，很多类上千行。改个图标、换套配色、修个搜索崩溃，半天能出活；想做现代化的界面、接新解码器、上 Compose，基本等于重写。

三、第二类：不碰原码，重写壳但兼容配置协议

有一个事实常被忽略：TVBox 的「配置协议」本身很简单——一份 JSON，里面列站点、给接口地址、指定解析方式。真正复杂的是壳里的播放器和爬虫加载机制，而这部分是可以用任何技术栈重做的。于是就有了这一批「一行原码没碰、但从零写了个 TVBox」的项目。

3.1FongMi/TV：现在的事实标准

FongMi/TV（约 10.3k 星，仍在活跃更新）是这条路上最成功的一个。它用 Java 从零重写，Leanback 极简界面，核心卖点是「自动跳过失效线路」和播放失败自动换源——这两点在体验上直接压过了原码分支。今天你在用的 OK 影视、WebHomeTV 之类，很多都是它的下游。

它的两个直接衍生项目值得单独提：okcaptain/TV（OK 影视）在 FongMi 基础上做业务增强；webhtv/webhtv（WebHomeTV）加了自定义 HTML 页面能力——如果你的二次开发需求是「首页要能自己排版」，这个思路比自己改 Compose 布局省事得多。

3.2换语言重写：Kotlin、Flutter、Swift、桌面 Java

这一批项目证明了一件事：壳是可以被任何语言重写的，只要协议对得上。

这类的二次开发逻辑和第一类完全不同：你不是在「修改一个老项目」，而是在「用现代技术栈实现一套已知协议」。好处是架构干净、能上 Compose/Media3/Flutter；代价是你得自己补齐协议里的所有边角——jar 包加载、hipy 脚本、直播回放、EPG，一项都不能少，否则用户的旧配置导进来就是一片空白。

四、第三类：App 之外的配套，服务端与接口层

这一类最容易被忽略，但对「能长期跑下去」来说反而最重要——因为它不涉及客户端分发，也不直接承载内容。

4.1alist-tvbox：把网盘变成 TVBox 的源

power721/alist-tvbox（约 3.2k 星）做的事很具体：把 AList 的目录包装成 TVBox 能读的接口，支持播放列表和搜索。你在网盘里存的自己的片子，通过它就能出现在 TVBox 的界面里。这是「自建源」这条路上最成熟的方案，比折腾爬虫稳得多。站内这篇自建接口的实操就是基于它的思路。

4.2爬虫模板：写自己的数据接口

TVBox 体系里的「源」本质是一段能返回结构化数据的代码。围绕这件事，社区有三种成熟模板：

4.3插件化：另一种思路

muedsa/TvBox（约 69 星）走的是和上面都不一样的路：把播放器做成「插件化媒体容器」，各种数据源以插件形式挂进来，官方仓库里还带着 bilibili、斗鱼、NO 视频等插件示例。星数不高，但架构思路是这一堆项目里最接近「长期可维护」的——它把「壳」和「源」的边界用接口彻底切开了。

五、真要动手，改的是这四层

不管你 fork 的是哪一类，二次开发实际能下手的只有四个位置。搞清楚自己改哪一层，比选哪个仓库更重要。

5.1壳层 UI

首页布局、海报墙、详情页、设置页。这是改动最频繁也最安全的一层，不涉及协议。第一类改的是 Java + 原生 View（部分 XML 布局），第二类里 AVBox 改 Compose、CatVodOpen 改 Flutter。牵动范围：只影响你看到的东西，不影响能不能播。

5.2播放内核

系统播放器 / IJK / ExoPlayer / Media3 / libVLC 的切换与参数调整。这一层最容易被低估：换内核要处理硬解兼容、音轨字幕、倍速、HDR，改不好就是「某些片能播某些片黑屏」。skycn-mi2/TVBox-VLC 就是专门做这件事的项目，可以当参考实现看。

5.3数据接口层

也就是「源」。加载 jar 包、执行 hipy/drpy 脚本、解析 JSON、做搜索聚合。这一层决定了「能搜到什么」，也是各家分支差异最大的地方（多源兜底、按优先级聚合、失效自动切换都在这里）。想自己写源，直接看第四节的爬虫模板，不用碰客户端代码。

5.4构建与分发

签名、多渠道包、arm64/armeabi 分包、自动构建。这一层没有技术含量但最容易卡住新人。o0HalfLife0o/TVBoxOSC 的 Actions 配置可以当模板抄。

六、挑仓库的五个判断标准

看完上面的分类，真到选的时候还有几个现实问题要过一遍：

一、最近一次提交。TVBox 生态变化很快，半年没提交的项目大概率已经跟不上新的接口格式。T 版就是典型例子：代码质量不错，但停更后上游的播放器修复拿不到。

二、语言是不是你的能力范围。Java 老项目改起来是「在别人的老房子里装修」，Kotlin/Compose 是「自己盖新房但要从头搬砖」。不会 Java 却想改 Q 版，会很痛苦。

三、协议实现是否完整。只支持 JSON 里最简单的站点列表，和完整支持 jar / hipy / 直播回放 / EPG，是两个难度量级。判断方法很简单：拿一份复杂点的配置导进去，看能不能全跑通。

四、License 和依赖。这类项目大量使用 GPL 系的播放器内核，二次分发时要注意；有些仓库还夹带闭源的 jar 包，那部分代码你既看不到也改不了。

五、Star 数只能当参考。前面说过，TVBox 关键词下高星的多是配置源。真正该看的指标是 commit 频率和 issue 里的实际问题。

七、这类项目的现实边界

最后说几句不太好听但必要的话。

这些播放器本身是空壳，代码是中性的，问题出在「源」上：绝大多数公开接口指向的是盗版影视站。国内这类应用涉及侵权，GitHub 上相关仓库也时常因为 DMCA 被清空——你 fork 的仓库某天突然消失，不是意外。

如果你要做的是自己用或者小范围用，建议把接口层做成可插拔的，只接自有内容（网盘的、自建的、有授权的）。这样项目既能长期维护，也不会因为上游被清而整个崩掉。版权边界与 jar 包安全那篇讲得更细，尤其是 jar 包会执行任意代码这一点，别随手加载来路不明的包。

另外提醒一句：本文列的仓库状态是 2026 年 11 月的快照，这类项目变动很快，动手前请自己再确认一次仓库是否还在、是否还活跃。