TVBox 的官方仓库在 2022 年 7 月就已经封仓停更，所以严格来说，今天你在电视盒子上装的每一个 TVBox、每一份「影视仓同款」，都是别人二次开发的产物。但「二次开发」这四个字底下藏着三种完全不同的技术路线：有的人在原码上改 UI，有的人一行原码都没碰、自己重写了一个壳，还有的人干脆不碰 App，只在服务端做接口。分不清这三类，看 GitHub 就会一片混乱——高星仓库里一半根本不是播放器，而是配置源。
这篇按「代码关系」而不是「版本名字」来分，把三类路线各自的代表仓库、技术栈、维护状态和真正该动手的地方讲清楚。看完你应该能判断：想改成什么样，该 fork 哪个仓库。
判断一个仓库属于哪一类，其实不用读代码，看三件事就够了：它是不是官方仓库的 fork、用什么语言写、以及它到底读不读 TVBox 那份 JSON 配置。
| 类型 | 与官方源码的关系 | 代表仓库 | 改动成本 | 适合谁 |
|---|---|---|---|---|
| 一、同源分支 | 直接 fork CatVodTVOfficial/TVBoxOSC，共用同一套 Java 代码底座 | Q 版、T 版、打包版、安卓 4.4 版 | 低（改几个类就能出 APK） | 想快速换皮、修 bug、适配老盒子 |
| 二、协议重写 | 不 fork，新代码库；只保证能读同一份配置 JSON | FongMi/TV、AVBox、CatVodOpen、FreeBox | 中高（但架构自由） | 想换技术栈、做跨平台、重做 UI |
| 三、周边配套 | 不在 App 内，跑在服务端或作为接口层 | alist-tvbox、TVSpider、dr_py | 中（但与前端解耦） | 想自建源、做自己的接口，不碰客户端 |
这三类的分野在现实里非常明显。第一类的仓库打开来，目录结构、包名、混淆方式几乎一模一样，改起来像在维护一份 2022 年的老项目；第二类打开是干净的现代 Android 工程，甚至压根不是 Android；第三类根本没有 APK，只有 Docker 镜像和配置文件。
甄宝园topic:tvboxosc 或者具体仓库名去找。所有这类项目的祖先都是 CatVodTVOfficial/TVBoxOSC——猫影视作者停更后公开的那份源码。它在 2022 年 7 月封仓，如今仓库本身也已经 404：源码被人独立重传成 j4Uq/TVBoxOSC（约 18k 星），各条分支也一直在接续修改。本节讲的就是这几条线。全部 46 个仓库的清单在这里。
Q 版（q215613905/TVBoxOS）是兼容性最好的一条，Android 4.x 的老盒子基本只能靠它。它的定位是「稳」：UI 朴素、改动克制、直播回放这类功能做得早。想给长辈的老盒子续命，或者你的设备 API 等级很低，就从这里 fork。
T 版（takagen99/Box，约 3.1k 星）是 Q 版之后 UI 改得最狠的一支，蓝黑配色、分辨率与网速屏显、中英双语、长按影片聚合搜索。它本身是官方仓库的 fork，代码结构相对清晰，是这三条线里最适合拿来做二次开发的起点：UI 层和业务层分得比较开，换一套配色或重排首页不用动播放逻辑。代价是它 2026 年 2 月之后基本停更了，上游的播放器内核修复拿不到。
o0HalfLife0o/TVBoxOSC 严格说不算「开发」，它是把 Q 版和 T 版编译成 APK 的发布仓库。但它对理解整个生态很关键：社区里流传的绝大多数「TVBox 官方版 APK」都是从这里出的，因为它把两套源码的构建流程自动化了。你要自己出包，可以直接抄它的 GitHub Actions 配置，省掉配 Gradle 和签名的一堆坑。
| 仓库 | 改了什么 | 适用场景 |
|---|---|---|
| mlabalabala/box | 重做多源处理逻辑，专门兼容 Android 4.4 | 库存老盒子、跑分低的电视棒 |
| skycn-mi2/TVBox-VLC | 把播放内核换成 libVLC，移除 IJK / EXO / 迅雷 | 某些编码格式只有 VLC 能硬解的设备 |
| ZxxXinI/tvbox | 用 Kotlin 重写的 Android TV 版，另有 tvbox-android4 兼容分支 | 想要新代码但仍是原生 Android |
| zongchenghuan0318/TVBox-fashion-UI | 在 TVBoxOSC 上加了豆瓣推荐、多源兜底聚合 | 看「业务层能加什么」的样本 |
这一类的共同特征是：上手极快，天花板也低。原码是 2022 年的 Java + 老版 ExoPlayer/IJK，包结构层层嵌套，很多类上千行。改个图标、换套配色、修个搜索崩溃，半天能出活；想做现代化的界面、接新解码器、上 Compose，基本等于重写。
有一个事实常被忽略：TVBox 的「配置协议」本身很简单——一份 JSON，里面列站点、给接口地址、指定解析方式。真正复杂的是壳里的播放器和爬虫加载机制，而这部分是可以用任何技术栈重做的。于是就有了这一批「一行原码没碰、但从零写了个 TVBox」的项目。
FongMi/TV（约 10.3k 星，仍在活跃更新）是这条路上最成功的一个。它用 Java 从零重写，Leanback 极简界面，核心卖点是「自动跳过失效线路」和播放失败自动换源——这两点在体验上直接压过了原码分支。今天你在用的 OK 影视、WebHomeTV 之类，很多都是它的下游。
它的两个直接衍生项目值得单独提：okcaptain/TV（OK 影视）在 FongMi 基础上做业务增强；webhtv/webhtv（WebHomeTV）加了自定义 HTML 页面能力——如果你的二次开发需求是「首页要能自己排版」，这个思路比自己改 Compose 布局省事得多。
这一批项目证明了一件事：壳是可以被任何语言重写的，只要协议对得上。
| 仓库 | 技术栈 | 特点 |
|---|---|---|
| XiaochangXu/AVBox | Kotlin + Jetpack Compose + Media3 | 约 590 星，手机版重写，UI 是这一批里最现代的，用 Media3 替代了老 ExoPlayer |
| catvod/CatVodOpen | Flutter | 猫影视「复活版」，一套代码覆盖 Win / macOS / Linux / iOS / Android |
| kknifer7/FreeBox | Java（桌面） | 约 2.1k 星，TVBox 电脑版，把电视端那套体验搬到 PC |
| jo32/tvbox-silicon | SwiftUI | 原生 Apple 平台（Apple TV / iPhone / Mac），生态里少见的一条路 |
| HurryBy/Playhub | Java + Web | Web 化播放器，支持直播源、EPG，浏览器里直接跑 |
| gstory0404/Cinetry | 多协议聚合 | 不止 TVBox，还接 Jellyfin / Emby / Alist / WebDAV，走「聚合客户端」路线 |
这类的二次开发逻辑和第一类完全不同：你不是在「修改一个老项目」，而是在「用现代技术栈实现一套已知协议」。好处是架构干净、能上 Compose/Media3/Flutter；代价是你得自己补齐协议里的所有边角——jar 包加载、hipy 脚本、直播回放、EPG，一项都不能少，否则用户的旧配置导进来就是一片空白。
这一类最容易被忽略，但对「能长期跑下去」来说反而最重要——因为它不涉及客户端分发，也不直接承载内容。
power721/alist-tvbox（约 3.2k 星）做的事很具体：把 AList 的目录包装成 TVBox 能读的接口，支持播放列表和搜索。你在网盘里存的自己的片子，通过它就能出现在 TVBox 的界面里。这是「自建源」这条路上最成熟的方案，比折腾爬虫稳得多。站内这篇自建接口的实操就是基于它的思路。
TVBox 体系里的「源」本质是一段能返回结构化数据的代码。围绕这件事，社区有三种成熟模板：
| 仓库 | 形态 | 说明 |
|---|---|---|
| jadehh/TVSpider | Java，猫影视/TVBox 爬虫合集 | 现成的站点爬虫参考实现，改改就能接自己的站 |
| bizhangjie/CatVodSpider | Java，约 540 星 | 自定义源接口的开发模板，结构最标准 |
| sec-an/TV_Spider | Python + Flask，约 295 星 | 服务端爬虫，用 Python 写规则，不必编译 jar |
| hjdhnx/dr_py | Python | 把普通网页站、X5 站点转成 CMS API 数据 |
muedsa/TvBox（约 69 星）走的是和上面都不一样的路：把播放器做成「插件化媒体容器」，各种数据源以插件形式挂进来，官方仓库里还带着 bilibili、斗鱼、NO 视频等插件示例。星数不高，但架构思路是这一堆项目里最接近「长期可维护」的——它把「壳」和「源」的边界用接口彻底切开了。
不管你 fork 的是哪一类，二次开发实际能下手的只有四个位置。搞清楚自己改哪一层，比选哪个仓库更重要。
首页布局、海报墙、详情页、设置页。这是改动最频繁也最安全的一层，不涉及协议。第一类改的是 Java + 原生 View（部分 XML 布局），第二类里 AVBox 改 Compose、CatVodOpen 改 Flutter。牵动范围：只影响你看到的东西，不影响能不能播。
系统播放器 / IJK / ExoPlayer / Media3 / libVLC 的切换与参数调整。这一层最容易被低估：换内核要处理硬解兼容、音轨字幕、倍速、HDR，改不好就是「某些片能播某些片黑屏」。skycn-mi2/TVBox-VLC 就是专门做这件事的项目，可以当参考实现看。
也就是「源」。加载 jar 包、执行 hipy/drpy 脚本、解析 JSON、做搜索聚合。这一层决定了「能搜到什么」，也是各家分支差异最大的地方（多源兜底、按优先级聚合、失效自动切换都在这里）。想自己写源，直接看第四节的爬虫模板，不用碰客户端代码。
签名、多渠道包、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 月的快照，这类项目变动很快，动手前请自己再确认一次仓库是否还在、是否还活跃。