上周A同学丢给我一份api.json，说他那边播得好好的，到我这儿 4K 片源一开就转圈，转十几秒出个画面，再过半分钟直接卡死。我打开文件扫了一眼——一百多行，三处尾逗号，两个中文引号，还夹了一行//注释。JSON 解析器在第一个尾逗号那里就已经放弃了，App 拿到的是一份残缺的配置，能启动全靠默认值兜底。这就是 TVbox 接口配置这件事的典型面貌：它看起来只是"填个地址"，实际上牵扯到 JSON 语法、字段语义、播放链路、码率预算、媒体库组织一整套东西。我把这几年折腾接口配置、4K 片源调优、自建源的完整路径整理一遍，从 JSON 怎么解析、每个字段对应什么动作，一直讲到怎么把自建媒体库变成能被读取的接口，以及后面长期的巡检和维护。适合刚拿到一份配置文件不知道怎么下手的新手，也适合已经能跑起来但始终搞不清"为什么这台设备行那台不行"的老手。

1. 接口文件先在纸上搞清楚：TVbox 到底在跟谁对话

1.1 一份接口配置的本质：一份"目录 + 说明书"

很多人把接口文件理解成"资源地址"，这个认知偏差会直接导致后面所有的排错都跑偏。接口文件本身不包含任何视频内容，它只是一份结构化的说明书，告诉客户端三件事：去哪里找内容、找到内容之后用什么方式播放、播放不了的时候交给谁去处理。用生活化的说法，它更像一张餐厅的菜单加上后厨的分工表，菜单上写着有哪些菜（sites 里的站点），分工表写着哪道菜由哪个厨师做（parses 里的解析规则），而真正的食材还在别人家的仓库里。

理解这一点之后，很多现象就顺了。比如"同一个接口，A 的盒子能播，B 的手机播不了"，大概率不是接口文件坏了，而是同一份说明书在两个客户端上被解读的方式不同，或者客户端版本对某个字段的支持程度不一样。再比如"接口昨天还好好的，今天全挂了"，那通常是说明书里写的那些外部地址变了，说明书本身一个字都没改。

所以配置接口的第一原则是：先把说明书读通，再去追究具体地址。我见过太多人一上来就挨个点站点试，试到一个能用的就存下来，结果下次换个设备又全废——因为他从来没搞清楚这份文件的结构，只是在碰运气。

还有一层需要说清楚：接口文件是一张目录，目录里放什么内容，取决于配置者自己。这里讨论的全部是自有媒体库、局域网共享、以及公开合法资源这几类场景，配置的核心价值在于把你自己手上有权使用的内容组织好、播得顺畅，这一点在后面自建源那一章会展开讲。

1.2 播放器、解析器、资源站点三方的关系

一份配置跑起来，实际上是三方在协作。资源站点提供页面或者接口数据；解析器负责从页面里把真正的播放地址抽出来；播放内核负责把这个地址渲染成画面。这三方任何一环出问题，表现出来的症状都是"播不了"，但排查方向完全不同。

我习惯用一张表把症状和环节对应起来，遇到问题先对号，比盲目改配置高效得多：

这张表是我自己排错时随手记的，不一定覆盖所有情况，但能省掉大量"什么都改一遍"的时间。关键在于：先定位环节，再动配置。跨环节乱改是新手最容易掉进去的坑，改到最后连哪一步改坏了都记不清。

1.3 开工之前必须确认的三件事

在动手写第一行 JSON 之前，有三件事必须先确认，否则后面全是返工。

第一是客户端版本。TVbox 这类的客户端有大量分支和衍生版本，字段支持程度差异不小。同一个playerType字段，在不同分支里对应的内核编号可能完全不一样。我踩过最狠的一次坑是照着某篇教程填了个playerType: 1，结果在用的那个版本里 1 代表的是软解，4K 直接卡成 PPT，折腾了两个小时才发现问题出在一个数字上。

第二是配置文件的托管方式。接口文件要能被客户端拉到，得有可访问的地址。常见的做法是放在自己的静态托管上，或者干脆放在局域网里的某台机器上。这里要注意的是，配置文件的地址会作为相对路径的解析基准——后面第 2 章会专门讲这个坑。

第三是内容来源的合法性。这一步不是走过场。自建源之所以值得花时间，恰恰是因为它的内容边界清清楚楚：你自己的影音收藏、你自己拍的素材、你有权使用的公开资源。把这块想明白，整个配置工作才有长期维护的意义。

2. JSON 逐层拆解：每行配置背后对应什么动作

2.1 顶层五个区块的分工

一份典型的配置长这样，我把它压到最小可运行规模，方便逐块看：

{ "sites": [], "lives": [], "parses": [], "flags": [], "spider": "", "wallpaper": "", "ads": [] }

这七个键里，前四个是干活的，后面三个是装饰和杂项。sites管点播，lives管直播，parses管解析规则，flags管解析器的优先级顺序。spider指向一个脚本或包文件，某些类型的站点依赖它才能工作，如果没有用到这类站点，留空即可。wallpaper是背景图，ads是广告位配置，很多精简版配置直接删掉这两个键也不影响运行。

这里有个容易被忽略的点：顶层键的顺序不影响解析，JSON 对象本身是无序的。但我建议保持固定顺序，原因是人工 diff 的时候顺序一致才能一眼看出改了什么。这个习惯在后期维护阶段价值很大，尤其是你手上同时管着好几份配置的时候。

另一个点是空数组和缺省值的区别。"parses": []和完全不写parses键，在很多客户端里表现一样，但在少数分支里会触发不同的降级逻辑。稳妥做法是：用到的区块写全，用不到的统一给空数组，别玩省略。

2.2 sites 数组：字段与取值的对应关系

sites是整份配置里最庞大也最容易写错的部分。每个元素描述一个内容入口，核心字段有这么几个：

{ "key": "mylib", "name": "我的媒体库", "type": 3, "api": "csp_MyLib", "searchable": 1, "quickSearch": 1, "filterable": 1, "ext": "" }

key是唯一标识，客户端内部用它做去重和缓存索引，重复了会出现各种诡异现象，比如点 A 站跳 B 站。我建议用有意义的前缀加短横线，比如lib-movie、lib-tv，别用1、2这种，几百个站点之后你根本分不清谁是谁。

name是显示名，随便写但要唯一，重名的话在列表里会出现两个一模一样的条目，点哪个全凭运气。

type决定这个站点走哪条协议通道。常见取值大致是：0走 XML 类型接口，1走 JSON 类型接口，3走需要脚本支持的接口。这里必须提醒一句，不同分支对 type 的取值定义可能有偏移，我手上就有两个版本对type: 1的处理逻辑不一样的记录。所以正确做法不是背数字，而是拿一个已知能用的最小配置去试，试出这个版本的实际映射关系，记在自己的笔记里。

api是最关键的一行。对于type: 3的站点，这里填的是脚本里的入口名，格式通常是csp_加类名，而这个类名必须能在spider指向的文件里找到对应实现，否则站点会直接不显示。这就解释了为什么很多人抄了一份配置回来，站点列表里少了一大半——spider没配对，或者版本不匹配。

searchable、quickSearch、filterable这三个开关控制搜索和筛选能力，取值0和1。全开会让列表加载变慢，因为客户端要预取更多数据；全关又会让使用体验很割裂。我的经验是：站点多的时候，只给常用的那几个开quickSearch，其余的按需开，能明显改善首屏速度。

2.3 lives 与 parses：直播分组和解析规则

lives的结构比sites简单得多，但它有个独特的分组语法需要单独说。

{ "name": "自建频道", "type": 0, "url": "http://192.168.1.10:8096/live/list.txt", "playerType": 1, "epg": "" }

url指向的通常是一个文本列表，内容按频道名,地址一行一条，分组用分组名,#genre#这样的独立行来切分。这个格式非常古老但极其好用，因为它可以纯手工维护，也可以脚本生成：

央视频道,#genre# 频道一,http://192.168.1.10/live/ch1.m3u8 频道二,http://192.168.1.10/live/ch2.m3u8 自建频道,#genre# 家庭摄像头,http://192.168.1.10/live/cam.m3u8

epg是节目单地址，指向一个 XMLTV 格式的文件。自建源场景下如果不需要节目单，留空就行，别为了"看起来完整"硬填一个不存在的地址，客户端会反复请求它，白白拖慢列表加载。

parses是解析规则列表，结构大致是{name, type, url, ext}。type区分是网页解析还是直接取直链，url是解析服务的地址，ext用来传额外参数，通常是一段 JSON 字符串。这个区块的坑在于优先级：flags数组里列出的那些标识决定了尝试顺序，没列进去的解析器可能在特定场景下被跳过。我遇到过"加了新解析器但完全没生效"的情况，最后发现是flags里没有对应项。

2.4 五类最常见的 JSON 语法事故与自查方法

这一节是我认为整篇最该先看的部分，因为 90% 的"配置无效"根本到不了功能层面，全死在这里。

第一类：尾随逗号。JSON 标准不允许数组或对象最后一个元素后面还有逗号。但 JavaScript 允许，所以很多人从 JS 对象里复制过来就带上了。这个错误在压缩成一行的时候几乎看不出来。

第二类：中文标点。中文输入法下的引号""和英文""在编辑器里长得像，在字节层面完全不同。还有中文逗号，。这类问题肉眼极难发现，用字体区分明显的编辑器能缓解，但根治要靠校验工具。

第三类：注释。JSON 不支持//和/* */。有些人为了让配置"好读"加注释，结果整份文件解析失败。

第四类：BOM 头。用某些编辑器保存 UTF-8 时会带上 BOM（字节序标记），三个不可见字节EF BB BF顶在文件开头，严格解析器会直接报错。这个问题特别隐蔽，因为文件用记事本打开看完全正常。

第五类：转义残缺。ext字段里要塞一段 JSON 字符串，里面的引号必须转义成\"。少转义一个，整份配置就崩了。我的做法是尽量不在ext里塞复杂结构，能用扁平键值就不用嵌套。

这五类问题最好的自查方式是跑一遍解析器，别靠眼睛。Python 一行就够：

import json, sys def check(path): raw = open(path, "rb").read() if raw[:3] == b"\xef\xbb\xbf": print("[警告] 文件带 BOM，需要先剥离") raw = raw[3:] try: data = json.loads(raw.decode("utf-8")) except UnicodeDecodeError as e: print("[失败] 编码不是 UTF-8:", e) return None except json.JSONDecodeError as e: print(f"[失败] 第 {e.lineno} 行第 {e.colno} 列: {e.msg}") line = raw.decode("utf-8", "replace").splitlines()[e.lineno - 1] print(" 该行内容:", line.strip()[:120]) return None print("[通过] 解析成功，顶层键:", list(data.keys())) return data check(sys.argv[1])

这个脚本比任何在线校验工具都好用，原因是它会打印出错行号和该行内容，尾逗号和中文引号基本一眼定位。我把它放在日常工具目录里，改完配置必跑一次。

还有一类不算语法错误但同样致命的问题：相对路径的基准变了。配置里写"spider": "./spider.jar"，本地测试的时候基准是你打开文件的目录，一切正常；上传到托管之后，基准变成配置文件所在的 URL，如果spider.jar没有一起传上去，或者被放在了子目录里，站点就会大面积失效。我第一次遇到这个坑时，本地跑得好好的配置上传后少了三分之二的站点，排查了很久才想到是相对路径问题。处理办法很简单：要么全部用绝对地址，要么保证上传时目录结构完全一致。

3. 4K 卡顿的定位链路：先分清是拉不动还是解不动

3.1 用码率算一遍账，很多问题当场就有答案

4K 卡顿这个事，绝大多数讨论都停留在"是不是网速不够"，但"网速"是个模糊概念，得换算成具体数字才能判断。核心公式很简单：

每小时数据量（GB）= 码率（Mbps）× 3600 ÷ 8 ÷ 1024

我列几个常见档位：

这张表能直接回答一类问题。比如有人抱怨"我家 300M 宽带播 4K 还卡"，如果是局域网自建源，宽带多少根本不参与传输，真正决定的是内网链路；如果是走外部网络的片源，那 300M 指的是下行带宽，但实际可用带宽受同时段占用、路由转发能力、无线信号质量共同影响，标称值打个六折是常态。

我自己的经验法则是：4K 高码率片源，优先走有线。一根网线能解决的问题，不要花两小时调参数。

3.2 起播慢和播放中卡顿的排查分岔口

"卡"这个词太笼统，必须拆成两种完全不同的现象。

起播慢指的是点了播放之后，要等很久才出画面，但一旦出画面就一直顺畅。这种问题的根源通常不在带宽，而在元数据位置或首片拉取。对于 MP4 封装的片源，关键在于moov原子（记录索引信息的数据块）的位置——如果它在文件末尾，播放器必须先把整个文件下载一遍才能开始播放。用ffprobe或者任意一个能看封装信息的工具都能查出来，重新封装一次（把moov挪到前面）就能解决。

播放中卡顿则表现为画面走走停停、反复缓冲。这才是带宽或解码能力的锅。区分方法很简单：把同一个片源换个码率更低的版本播，如果顺畅了，是带宽问题；如果照样卡，那大概率是解码。

我把这两条链路的排查要点整理成一张对照表，遇到问题照着走：

3.3 解码方式与播放内核的取舍

解码这块，硬件解码和软件解码的选择不是"哪个更高级"，而是"哪个更适合当前设备"。

硬件解码把解码工作交给设备的专用电路，功耗低、发热小、能扛高码率，但兼容性受芯片支持范围限制。老一些的设备对 HEVC 10bit、AV1 这类规格支持不全，硬解一开就花屏或直接黑屏。软件解码兼容性好，什么格式都能试，但吃 CPU，4K 高码率下很容易把 CPU 打满，表现为画面卡顿伴随明显发热。

我的判断顺序是：先用硬解试，能正常播放就保持；出现花屏、绿边、黑屏、音画不同步，立刻切软解验证。如果软解正常，说明是硬解的兼容问题，那就在"这台设备播这个片源"的组合上记一笔，不用去动全局配置。

至于播放内核，这里必须强调一个前面提过的事：不同客户端版本对内核编号的定义不一样。我见过把playerType填1在 A 版本上是硬解、在 B 版本上是软解的情况。所以正确做法是拿同一部 4K 片源，把内核选项挨个试一遍，记录下"这台设备 + 这个版本 + 这个编号 = 什么效果"，形成自己的小抄。这个笨办法比任何教程都靠谱，因为教程作者用的版本大概率和你不同。

提示：调内核参数时一次只改一个字段，改完立刻用同一部片源复测。同时改三个参数，你会失去归因能力，最后只能全部推倒重来。

3.4 缓冲参数与分片策略的调整边界

缓冲相关的参数确实能改善体验，但它的作用被严重高估了。缓冲的本质是"用内存和启动延迟换流畅度"，它不能让一条带宽不足的链路变宽。

以常见的播放内核参数为例，通常会有一组bufferForPlaybackMs（起播前最少缓冲时长）、maxBufferMs（最大缓冲上限）、bufferForPlaybackAfterRebufferMs（重缓冲后重新起播的缓冲量）之类的配置。调整逻辑是：链路抖动大，适当调高起播缓冲，用更长的等待换取更少的中间停顿；设备内存紧张，就得压低最大缓冲上限，否则播到一半会因为内存不足崩溃。

我遇到过一台内存只有 1G 的老盒子，4K 片源播到二十分钟左右必然闪退，把最大缓冲上限调低之后问题消失，代价是缓冲次数变多。这就是典型的权衡，没有免费午餐。

分片策略方面，HLS 类型的片源可以关注分片时长。分片太长，起播慢、seek 粒度粗；分片太短，请求次数暴涨，对小服务器不友好。自建场景下我一般用 4–6 秒的分片，兼顾起播速度和请求压力。这个值不用追求极致，够用就行。

4. 自建源的落地路径：从媒体库到能被读取的接口

4.1 媒体服务器的选型与目录命名规范

前面三章讲的都是"怎么把别人的说明书读通"，这一章讲"怎么写自己的说明书"。自建源的意义在于：内容边界清晰、可控、不依赖外部变化，长期来看维护成本反而最低。

选型上，市面上有几类方案可选：一类是完整的媒体服务器软件，自带刮削、转码、多端播放能力；一类是轻量的文件共享（WebDAV、SMB），把目录结构直接暴露出去；还有一类是纯静态文件服务，简单粗暴但够用。我不做具体产品推荐，只讲选择逻辑：

• 需要海报墙、剧集自动归集、多用户，选完整媒体服务器。
• 只需要"能播"，且片源命名规范，选文件共享或静态服务。
• 需要在播放时实时降低码率适配弱设备，选带转码能力的方案。

不管选哪种，目录命名规范是所有方案的地基。我的规范是这样：

/Media /Movies /影片名 (2020) 影片名 (2020) - 2160p.mkv /TV /剧名 (2021) /Season 01 剧名 - S01E01 - 2160p.mkv

这个规范的唯一目的是让自动识别尽可能准确。年份放在括号里、季集用S01E01格式、分辨率标记放在最后，这几条是绝大多数工具的通用识别规则。命名不规范带来的后果是"能播但归类混乱"，看起来不致命，实际上会让整个自建源的可用性大打折扣——你会在几百个文件里找不到想看的东西。

还有一个容易忽略的点：同名不同版本的处理。同一部影片有 1080P 和 4K 两个版本时，最好放在不同子目录，或者在文件名里做明确区分，别让工具自己去猜哪一个是主版本。

4.2 用脚本把本地媒体库导出成接口文件

这是自建源最关键的一步：把文件系统里的内容，转成客户端能读的接口结构。

对于直播列表这种纯文本格式，脚本非常简单：

import os, pathlib ROOT = pathlib.Path("/Media/Live") BASE = "http://192.168.1.10:8080/stream" lines = [] for group_dir in sorted(ROOT.iterdir()): if not group_dir.is_dir(): continue lines.append(f"{group_dir.name},#genre#") for f in sorted(group_dir.glob("*.m3u8")): title = f.stem url = f"{BASE}/{group_dir.name}/{f.name}" lines.append(f"{title},{url}") lines.append("") pathlib.Path("list.txt").write_text("\n".join(lines), encoding="utf-8") print(f"生成 {len(lines)} 行")

对于点播，思路是把媒体库的目录结构映射成sites里的条目，或者生成一份 JSON 供本地站点读取。这里有个取舍：sites条目太多会让客户端首屏变慢，所以更常见的做法是只注册一个入口站点，把具体的影片列表放在站点内部的数据文件里，客户端按需拉取。这个设计思路和"少注册站点、多开子分类"是一回事。

写这类脚本有几个必须注意的点。第一是编码，输出文件统一用 UTF-8，不要用系统默认编码，Windows 上默认 GBK 会产生乱码。第二是路径分隔符，生成 URL 时统一用/，别用os.path.join拼 URL。第三是排序，一定要显式排序，否则每次生成的文件顺序都不一样，版本管理全是噪音。

4.3 局域网访问的地址写法与常见踩坑

自建源 90% 的失败原因都出在地址上，我把踩过的坑列一遍。

用主机名还是 IP。主机名在支持 mDNS 的环境下没问题，但很多客户端解析不了，表现为"地址不可达"。我的做法是：自建源一律用固定 IP，并且在路由上给那台机器做静态地址绑定，避免 DHCP 重新分配导致接口突然全挂。

端口和防火墙。服务起来了但访问不了，先查防火墙。这一步听着简单，但我见过太多人折腾一小时配置，最后发现是系统防火墙拦了端口。

相对路径的基准问题。这个在第 2 章提过，在自建场景下更常见。接口文件里写的url如果是相对路径，会以接口文件本身的地址为基准解析。托管在子目录里的时候，算出来的地址经常是错的。稳妥做法还是全用绝对地址。

URL 编码。中文文件名和空格在 URL 里必须编码。有些客户端处理得比较宽松，有些会直接失败。我的做法是生成列表时就用urllib.parse.quote处理一遍，别指望客户端兜底。

重定向。如果自建服务前面有反向代理，配置了强制跳转，客户端可能会因为不跟随重定向而失败。这种问题在浏览器里测是通的（浏览器自动跟随），在客户端里就是不通，非常迷惑。

跨域响应头。这条容易被误判。某些在线预览工具是在浏览器里发请求的，受同源策略限制，缺Access-Control-Allow-Origin就报错；但原生客户端不受这个限制，同一份配置在 App 里完全正常。所以不要用浏览器预览的结果作为配置有效性的判断依据，这是我踩过的最浪费时间的一个坑。

4.4 让自建源"看起来和别人一样"的几个细节

技术上跑通之后，还有一些细节决定用起来顺不顺手。

图标和元数据。给站点和频道配图标，会让列表的可读性提升一个档次。图标地址同样要求绝对路径，且最好是客户端能直接访问的格式，别用需要登录才能拿到的图床。

加载耗时。自建源最大的优势是可以做性能优化。列表文件控制在几百 KB 以内，别塞几千条；接口响应加上缓存头，客户端重复请求时能命中缓存。我试过把一个两万行的列表拆成按分类分文件，首屏加载时间从七八秒降到一秒多，差别非常明显。

容错设计。任何一个自建服务都可能临时挂掉，接口设计时应该考虑这个。比如把列表文件做成静态的、服务重启期间仍然可读；或者准备一份降级的最小列表，主服务不可用时至少还能看到几个常用频道。这个思路来自于"不要把所有鸡蛋放在一个筐里"。

5. 长期维护：把接口当成一个需要运维的小系统

5.1 失效的三种典型信号

接口配置不是一次性工作，它需要持续维护。失效通常有三种信号，识别出来能省很多时间。

信号一：整体结构还在，但部分条目消失。客户端能正常加载配置，站点列表也有，但比之前少了一些。这通常是spider版本不匹配，或者某个外部地址返回了非预期内容导致该条目被跳过。

信号二：列表能出，点进去报错。说明站点入口还在，但内部数据接口变了。这类失效最需要及时处理，因为它占着位置但完全不可用。

信号三：能播但质量明显下降。比如原来 4K 的片源现在只有 1080P，或者原来秒开的现在要等十秒。这不一定是"失效"，可能是服务端降级了。这种信号最容易被忽略，但往往预示着更大的问题。

我给自己的规矩是：每天花两分钟看一眼首页加载情况，比每周花两小时集中排查高效得多。小幅度的持续观察能提前发现趋势，集中排查只能事后救火。

5.2 一个够用的巡检脚本

巡检不需要多复杂，能回答"还能不能访问"和"响应有多快"这两个问题就够。

import time, csv, concurrent.futures as cf import urllib.request, urllib.error TIMEOUT = 6 def probe(item): name, url = item t0 = time.time() req = urllib.request.Request(url, headers={"User-Agent": "probe/1.0"}) try: with urllib.request.urlopen(req, timeout=TIMEOUT) as r: size = len(r.read(4096)) return (name, url, r.status, f"{(time.time()-t0)*1000:.0f}", size) except urllib.error.HTTPError as e: return (name, url, e.code, f"{(time.time()-t0)*1000:.0f}", 0) except Exception as e: return (name, url, "ERR", f"{(time.time()-t0)*1000:.0f}", str(e)[:40]) targets = [ ("自建点播", "http://192.168.1.10:8080/api.json"), ("自建频道", "http://192.168.1.10:8080/live/list.txt"), ] with cf.ThreadPoolExecutor(max_workers=8) as pool: for row in pool.map(probe, targets): print(row)

这个脚本有几个设计考虑值得说。用线程池并发，因为串行探测几十个地址会很慢，并发能把总耗时压到最慢那一个的水平。只读前 4KB，目的是既验证了可访问性又不把整个文件拉下来，省带宽。记录响应时间，这是判断"能不能用"之外的第二维度，响应时间从 100ms 涨到 3000ms 往往意味着服务端出问题了。捕获 HTTPError 单独处理，因为 404 和超时是两种完全不同的故障，混在一起没法定位。

跑一段时间之后可以把结果存成 CSV，画个曲线，趋势一目了然。我自己的库里存了大半年的巡检记录，能清楚看到某个地址是从哪天开始变慢的。

5.3 多配置共存与灰度切换

顺手的时候可以只维护一份配置，但只要设备多、场景多，就会需要多份。

我的做法是按用途分三份：主力配置（日常用，条目精选，追求响应速度）、完整配置（全量，用来查漏）、实验配置（新加的东西先放这里试）。客户端支持多配置切换，出问题的时候切一份对比，能立刻判断是配置问题还是环境问题。

灰度切换的意思是：改配置不要直接覆盖主力那份。正确流程是先在实验配置上改，用一周，确认没问题再合并进主力。听起来有点重，但真的能避免"改完之后发现某个常用功能挂了，而你已经记不清改了什么"这种局面。

这里有个小技巧：给每份配置留一个版本标记字段。可以在wallpaper或者某个不影响功能的字段里写入版本号和日期，比如"wallpaper": "v20240612"。出问题的时候一眼就能知道客户端当前加载的是哪个版本，比翻文件时间戳可靠得多。

5.4 版本管理：用 git 管住你的 api.json

配置文件用 git 管，这件事我强烈建议做。原因很实在：JSON 文件改动频繁、格式严格、出问题全靠对比。

cd ~/tvbox-config git init git add api.json list.txt git commit -m "初始版本：自建点播 + 本地频道" # 每次改动后 git add -A git commit -m "调整 4K 片源缓冲参数"

配上一条查看差异的命令，改了什么一目了然：

git diff --stat git diff -- api.json

好处有三个。第一是回溯，任何一次改动都能回到之前的状态，改坏了不慌。第二是归因，某个问题什么时候出现的，翻 log 就知道。第三是防丢，本地文件误删、误覆盖这种事，有版本库就是几分钟的事，没有就得从头重写。

还有一个配套习惯：生成类文件不入库。像前面那个扫描目录生成list.txt的脚本，生成结果不应该进 git，应该只入库生成脚本本身，配合.gitignore：

list.txt *.log

这样每次重新生成不会产生一堆无意义的 diff，提交记录里全是真正的人工改动。

我自己在实际操作中的体会是，配置这件事最花时间的从来不是"写出第一版"，而是"半年后还能快速定位问题"。前者可能一个下午就搞定，后者考验的是你有没有留下足够的线索——版本记录、巡检日志、字段含义笔记，这三样东西齐全，半年后接手也能十分钟上手；缺任何一样，就得重新摸索一遍。前面那些看起来啰嗦的规范和脚本，本质上都是在给未来的自己铺路。