1. 从一条更新帖说起：TVBox源接口到底在折腾什么
每年总有那么几个时间点，各个影视资源社群里会突然热闹起来——不是新剧上线，而是又有人开始整理新一期的源接口清单了。我手上这个项目就是从2026年8月那波整理开始的，最初只是给自己和朋友维护一份能用的接口列表，后来越滚越大，变成了一个长期更新的仓库。核心关键词就三个：TVBOX、源接口、JAR包。这三个词基本概括了整个生态的运转逻辑。
先把话说清楚：TVBox本身是一个开源的播放器外壳，它自己不带任何内容，所有能看的东西都来自外部配置——也就是大家常说的“源”。这个源可以是一个远程的JSON地址，也可以是一个本地打包好的文件，里面写清楚了直播频道、点播分类、资源站地址、解析规则等等。而JAR包则是TVBox的扩展能力载体，很多复杂的解析逻辑、特殊站点的处理，都是通过加载JAR来实现的。所以一份“能用的源”，本质上就是一份配置合理的JSON加上配套的JAR依赖。
这个项目适合谁看？三类人。第一类是普通用户，只想找一份稳定能用的配置，不想折腾代码；第二类是有点动手能力的玩家，想自己改改JSON、换换线路、调调排序；第三类是想自己搭一套本地源、甚至把JAR包管理起来的技术型玩家。我下面会从整体思路讲到具体操作，尽量让三类人都能各取所需。需要提前说明的是，文中涉及的所有地址、包名、参数都是示例性质，实际使用时请以你自己环境里的为准，我不会提供任何具体的资源站地址。
2. 整体设计思路：为什么是JSON加JAR这套组合
2.1 配置与能力分离的设计哲学
TVBox这套架构最聪明的地方，就是把“数据”和“逻辑”拆开了。JSON负责描述“有什么”——有哪些分类、每个分类下有哪些站点、站点的接口地址是什么；JAR负责描述“怎么处理”——遇到一个特殊的加密接口怎么解、遇到一个需要特殊header的请求怎么发。这种分离带来的直接好处是：改内容不用重新编译，改逻辑不用动配置。
我见过不少人一开始不理解为什么要搞两个东西，觉得一个JSON全写完不就行了。实测下来，纯JSON方案在简单场景下确实够用，但一旦遇到需要动态拼接参数、需要处理重定向、需要做二次解析的站点，JSON就无能为力了。这时候JAR的价值就体现出来了——它本质上是一段可以热加载的Java代码，TVBox在运行时会通过反射调用里面约定的方法。
提示：JSON和JAR的版本要匹配。我踩过的坑就是拿了一个新版的JAR去配老版JSON，结果字段名对不上，整个点播分类直接空白。后来养成习惯，每次换JAR都先看它的说明文档里要求的配置格式版本。
2.2 远程源与本地源的取舍
整理源接口时第一个要决策的就是：做远程还是做本地。远程源的好处是更新方便，你改一次服务器上的文件，所有用这个地址的人下次启动就自动生效；坏处是依赖网络，而且一旦地址被大量使用，容易被限流甚至失效。本地源的好处是稳定、可控、不怕被墙外因素影响；坏处是每次更新都要重新分发文件，用户得手动替换。
我的做法是两条腿走路：日常用远程源做主力，同时维护一份本地打包版本作为备份。本地包的制作流程后面会详细讲，核心就是把JSON和JAR一起塞进一个压缩包，TVBox支持直接读取本地文件。这样即使远程地址挂了，用户切换到本地包还能继续用。
2.3 长期更新机制怎么设计
“长期更新”这四个字说起来轻松，做起来是个体力活。资源站会失效、接口会改版、解析规则会过期，如果每次都手动改一遍再发出去，根本撑不了多久。我现在的做法是建立一个检查清单，每周固定时间过一遍：先跑一遍自动化脚本检测所有接口的连通性，把返回异常的标记出来；然后人工抽查几个重点分类，确认内容质量；最后统一更新版本号并记录变更日志。
版本号我用的是日期加序号的形式，比如2026.08.15-01，这样用户一眼就知道自己手上的是不是最新的。变更日志写在仓库根目录的一个文本文件里，简单记录“新增X个站点、移除Y个失效站点、修复Z个解析问题”，方便回溯。
3. 核心细节拆解：JSON结构、JAR加载与字段含义
3.1 一份典型JSON配置的骨架
先看结构。一份完整的点播配置JSON，顶层通常有这几个关键字段：sites（站点数组）、lives（直播源数组）、parses（解析规则数组）、flags（标志位）、rules（规则）、wallpaper（壁纸）等。其中sites是核心，每个元素描述一个资源站。
{ "sites": [ { "key": "example_site", "name": "示例站点", "type": 3, "api": "https://example.com/api.php/provide/vod/", "searchable": 1, "quickSearch": 1, "filterable": 1, "ext": "https://example.com/jar/example.jar" } ] }这里几个字段值得展开说。type决定用哪种解析器，常见的有type 0（xml）、type 1（json）、type 3（苹果CMS风格）等，选错了整个站点就废了。api是资源站的接口地址，注意结尾的斜杠有时候不能少，我遇到过因为少一个斜杠导致搜索一直返回空的情况。ext字段是JAR的地址，当这个站点需要特殊处理时才会用到。
3.2 JAR包在TVBox里是怎么被加载的
TVBox加载JAR的机制，简单说就是：读取ext字段里的地址，下载到本地缓存，然后用DexClassLoader动态加载，最后通过反射调用里面约定的类和方法。这个约定的类名通常是com.github.tvbox.osc.parser包下的某个Parser实现，方法签名也是固定的。
这就解释了为什么JAR包不能随便乱放——它必须符合TVBox的接口规范。你自己写一个JAR，如果类名或者方法签名不对，加载时会直接抛异常，表现为“站点无法访问”或者“解析失败”。我调试JAR的时候，最常用的手段就是看TVBox的日志输出，里面会打印加载失败的堆栈信息，顺着堆栈基本能定位到问题。
注意：JAR包的体积不要太大。我试过把一个带了很多依赖的JAR塞进去，结果加载时间明显变长，低配设备上甚至直接卡死。后来学乖了，写JAR时尽量只保留必要逻辑，第三方库能不用就不用。
3.3 直播源配置的几个关键点
直播部分和点播不太一样，它用的是lives数组，每个元素是一个直播源，里面再嵌套channels频道列表。频道列表的格式通常是“频道名,地址#备用地址”这种形式，多个地址用井号分隔，TVBox会依次尝试。
{ "lives": [ { "name": "示例直播", "type": 0, "url": "https://example.com/live.txt", "playerType": 1 } ] }playerType这个字段容易被忽略，但它决定了用哪个播放内核。有些直播流用默认内核播不了，换成另一个就好了。我的经验是，整理直播源时把每个源的playerType都标注清楚，用户遇到播放问题时可以自己切换试试。
3.4 解析规则与嗅探的配合
parses数组里放的是解析规则，每条规则包含name、type、url、ext等字段。当点播站点返回的是一个需要二次解析的播放页时，TVBox就会调用这些解析规则去拿真实地址。type常见的有1（json解析）、2（json扩展）、3（嗅探）等。
嗅探模式比较特殊，它不依赖固定的接口，而是通过分析网页里的请求来抓取视频地址。这种方式通用性强，但速度慢，而且对某些加密站点无效。我整理时会把嗅探规则放在后面作为兜底，优先用固定接口的解析规则，这样速度更快。
4. 实操过程：从零做一份本地源包
4.1 环境准备与工具清单
动手之前先把家伙什备齐。我用的环境是Windows加JDK 17，打包JAR用Maven，编辑JSON用VS Code加JSON插件，测试用一台安卓电视盒子和一台备用手机。如果你只想改JSON不想碰代码，那JDK和Maven可以跳过，有个文本编辑器就够了。
工具清单如下：
| 工具 | 用途 | 备注 |
|---|---|---|
| JDK 17 | 编译JAR | 版本别太低，有些新语法不支持 |
| Maven | 依赖管理与打包 | 也可以用Gradle，看个人习惯 |
| VS Code | 编辑JSON | 装个JSON格式化插件 |
| 安卓设备 | 实测验证 | 最好有两台，一台主力一台备用 |
| 抓包工具 | 分析接口 | 用于排查接口问题 |
4.2 编写并打包一个自定义JAR
假设你要写一个简单的解析器，处理某个特殊站点的播放地址。步骤大致是：新建Maven项目，引入TVBox的接口依赖（或者手动把接口类复制进来），实现约定的Parser接口，然后打包。
mvn clean package -DskipTests打包完成后，在target目录下会生成一个JAR文件。注意，如果你的项目依赖了第三方库，默认打出来的JAR是不包含依赖的，需要额外配置maven-assembly-plugin或者maven-shade-plugin打成fat jar。我一开始就是忘了这一步，结果JAR加载时报ClassNotFound，查了半天才发现是依赖没打进去。
提示：打包时把版本号写进文件名，比如
example-parser-1.0.0.jar，这样以后更新时能一眼看出用的是哪版。我见过有人用parser.jar这种名字，结果新旧版本混在一起，根本分不清。
4.3 制作本地源包的完整流程
本地源包的本质就是一个压缩包，里面包含JSON配置文件和JAR文件。TVBox支持读取本地文件，所以你可以把整个包放到设备的存储里，然后在配置地址里填本地路径。
具体步骤：
- 新建一个文件夹，命名为你的源包名，比如
mysource。 - 把编辑好的JSON文件放进去，命名为
config.json。 - 把需要的JAR文件也放进去，可以建一个
jar子目录统一管理。 - 修改JSON里的
ext字段，把远程地址改成相对路径，比如./jar/example-parser-1.0.0.jar。 - 把整个文件夹压缩成zip包。
- 把zip包传到设备上，在TVBox的配置地址里选择本地文件。
这里有个细节：相对路径的写法在不同版本的TVBox里可能略有差异，有的版本要求用file://前缀，有的直接写相对路径就行。我的做法是两种都试一遍，哪个能跑通用哪个。
4.4 远程源的部署与更新
远程源就是把JSON和JAR放到一个可访问的服务器上，然后在配置地址里填URL。部署时注意几点：服务器要支持HTTPS，不然有些设备会拒绝加载；文件要有正确的MIME类型，JSON返回application/json，JAR返回application/java-archive；最好加个CDN或者缓存，避免大量请求打爆服务器。
更新流程我一般是这样的：先在本地改好JSON，测试通过后上传到服务器，然后修改版本号，最后在社群里发一条更新通知。通知里只写版本号和主要变更，不写具体地址，避免被滥用。
5. 常见问题与排查技巧实录
5.1 接口失效的快速定位方法
接口失效是最常见的问题，表现是点开某个分类一直转圈或者提示“获取数据失败”。排查思路是从外到内：先用浏览器或者curl直接访问接口地址，看返回什么；如果返回正常，说明是TVBox这边的问题，检查JSON里的字段有没有写错；如果返回异常，说明接口本身挂了，需要换源。
curl -I "https://example.com/api.php/provide/vod/"这个命令只看响应头，能快速判断接口是否可达。如果返回403或者404，基本可以确定接口地址变了或者被封了。
5.2 JAR加载失败的典型原因
JAR加载失败的表现通常是“解析错误”或者“站点无法访问”，日志里会有ClassNotFoundException或者NoSuchMethodException。常见原因有这么几个：类名写错了、方法签名不对、依赖没打进去、JAR版本和TVBox版本不兼容。
我整理了一个速查表：
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| ClassNotFoundException | 类名错误或依赖缺失 | 检查类名，打成fat jar |
| NoSuchMethodException | 方法签名不匹配 | 对照接口文档核对参数 |
| 加载超时 | JAR体积过大 | 精简依赖，压缩体积 |
| 解析结果为空 | 逻辑错误或接口改版 | 加日志，逐步调试 |
5.3 播放卡顿与线路切换
播放卡顿不一定是源的问题，也可能是线路本身的问题。我的做法是在JSON里给同一个站点配置多个线路，用户可以在播放器里手动切换。配置方式是在sites里加多个相同key但不同api的条目，或者用ext字段里的参数来区分。
注意：线路不是越多越好。我试过给一个站点配了七八条线路，结果加载列表时明显变慢，因为TVBox要逐个去请求。后来精简到三条，速度和质量平衡得比较好。
5.4 版本兼容性踩坑记录
TVBox的版本迭代比较快，不同版本对JSON字段的支持程度不一样。我遇到过最坑的一次是，新版TVBox要求searchable字段必须是数字，而我写的是布尔值，结果搜索功能直接失效。后来养成了一个习惯：每次升级TVBox版本，先拿一份最小配置测试一遍，确认所有字段都能被正确解析，再更新正式配置。
6. 长期维护的心得与扩展思路
维护这个源接口清单一年多，最大的体会是：自动化能解决的事，千万别手动做。我现在有一套脚本，每天定时跑一遍所有接口的连通性检测，把结果写进一个报告文件。每周我只需要看一遍报告，把标红的接口处理掉就行。这套脚本不复杂，核心就是遍历JSON里的所有api字段，逐个发请求，记录响应时间和状态码。
另一个心得是留好退路。每个站点至少保留一个备用接口，每个JAR至少保留一个旧版本。我见过太多人只维护一份配置，结果接口一挂就抓瞎。我的仓库里永远有一个backup目录，里面放着上一版的完整配置，随时可以回滚。
扩展方面，我最近在尝试把配置拆分成多个模块，比如点播一个文件、直播一个文件、解析规则一个文件，然后用一个主文件去引用它们。这样做的好处是更新时只需要改对应的模块，不用动整个大文件。TVBox本身支持这种拆分方式，通过include字段或者多个配置地址来实现。如果你也想做长期维护，强烈建议从第一天就用这种模块化思路，后期会省很多事。
最后分享一个小技巧：给每个站点加一个note字段，写上这个站点的特点、更新时间、维护人。这个字段TVBox不会解析，纯粹是给自己看的。等配置积累到几百个站点时，你会感谢当初做了这个记录的自己。
