JSON拼写错误如何毁掉一次发布？Obtainium Emulation Pack校验体系validate-json.py深度解析

Obtainium Emulation Pack 是一个把主流 Android 模拟器应用打包成 Obtainium 导入文件的项目，它靠 src/applications.json 这一个数据文件驱动整个发布流程。而 scripts/validate-json.py 正是守护这份数据的质量门禁——它能在发布前揪出 JSON 拼写错误、缺失字段和重复应用 ID，避免一个字母的笔误毁掉整次发布。

一个字母的代价：拼写错误为什么这么危险 🧨

这个项目的数据文件里，每个应用都带有一个可选的meta对象，用来控制"这个应用是否进入标准版/双屏版发布包、展示名怎么显示"。以 src/applications.json 中的 Cemu 为例：

"meta": { "includeInDualScreen": false }

这行配置的意思是：标准版 Cemu 不出现在双屏版发布包里。看起来很简单，但如果你不小心把它写成includeInDaulScreen或inlcudeInDualScreen……

没有任何报错。

JSON 语法完全合法，脚本照常运行，只是配置被静默忽略——双屏用户会看到本该排除的 Cemu 混进他们的发布包，与另一款同 ID 的 Cemu 分支互相冲突，导入直接失败。这类错误肉眼审查几乎不可能发现，直到用户反馈才暴露。

这正是 RELEASE.md 中 v7.0.0 版本要解决的核心问题：

添加一个新应用意味着手工编辑 applications.json，复制模板配置，然后祈祷自己没有引入拼写错误。

校验体系全景：validate-json.py 检查什么 🔍

validate-json.py 的结构非常清晰，整个校验由三层防线组成：

第一道防线：必填字段与类型检查

每个应用必须有 4 个字段，这是 validate-json.py 中的硬性要求：

同时还会检查categories必须是列表类型——写成字符串而不报错，会让后续的表格生成脚本直接崩溃。

第二道防线：meta 键白名单

项目只接受 6 个合法的meta键：excludeFromExport、excludeFromTable、nameOverride、urlOverride、includeInStandard、includeInDualScreen（见 validate-json.py）。

出现白名单之外的键，立刻报错并贴心地提醒你：

Cemu: unknown meta key 'exludeFromExport' (typo?)

注意那个(typo?)——脚本设计者早就预判了你可能会手滑。

第三道防线：内置拼写纠错表

更巧妙的是，脚本维护了一张"已知错误拼写 → 正确拼写"的映射表（validate-json.py）：

typo_checks = { "exludeFromExport": "excludeFromExport", "exludeFromTable": "excludeFromTable", "nameOveride": "nameOverride", "urlOveride": "urlOverride", }

这四个拼写错误显然是从真实历史事故中收集来的。命中后报错信息会直接给出正确写法，你不需要翻文档：

Cemu: typo in meta key 'nameOveride', should be 'nameOverride'

从"发现问题"到"如何修复"一步到位——这是非常贴心的工程实践。

第四道防线：重复 ID 检测

Obtainium 的规则是：同一发布包内，两个应用的 Android 包名（id）不能相同，否则导入时互相覆盖。

本项目支持standard（标准版）和dual-screen（双屏版）两个变体，像 Cemu 这类应用会同时存在"标准版"和"双屏专用分支"两条记录，且包名完全相同。因此 check_duplicate_ids 函数会按变体分别检查：

• 先根据excludeFromExport、includeInStandard、includeInDualScreen过滤出该变体实际会导出的应用
• 再在过滤后的集合里找重复 ID

这样"两个 Cemu 各进各的包"是合法的，而"两个 Cemu 都进标准版"会被立刻拦下：

Duplicate ID 'info.cemu.cemu' in standard variant: 'Cemu' and 'Cemu'

这套过滤逻辑与 scripts/utils.py 中真正生成发布包时使用的 should_include_app 函数遵循同一套优先级规则，保证了"校验时的预期"和"实际导出的结果"完全一致。

如何运行校验：make validate 最快上手 ⚡

校验脚本本身只需一行命令：

python scripts/validate-json.py src/applications.json

但推荐走 Makefile 封装好的入口，一条命令搞定：

make validate

输出只有两种结局：

• Validation passed: 40 apps checked—— 全部通过
• Validation failed with 2 error(s):—— 逐条列出所有问题，且一次全列出来，不用改一个跑一次

它在发布流水线中的位置 🏭

单独跑校验只是第一步。看 Makefile 中的release目标就明白了：

release: validate readme minify minify-dual-screen

完整发布顺序是：

1. validate—— 先校验 src/applications.json
2. readme—— 生成 README 应用表格（依赖 pages/table.md 等页面）
3. minify—— 生成标准版发布文件 obtainium-emulation-pack-latest.json
4. minify-dual-screen—— 生成双屏版发布文件 obtainium-emulation-pack-dual-screen-latest.json

注意校验排在最前面：只要 JSON 有问题，后续的压缩导出、README 生成统统不会执行。这就是"先守门、再生产"的经典流水线设计——scripts/minify-json.py 这类生产脚本因此永远只拿到干净的数据。

给贡献者的 3 条建议 ✅

1. 提交前必跑make release：这是 pages/development.md 中"Pre-Commit Checklist"的第一要求，它能同时完成校验 + 重新生成全部发布文件。
2. 加应用优先用make add-app：交互式命令行会自动填好id、url、author、name四个必填字段和标准 Obtainium 配置，从源头杜绝手写 JSON 的拼写风险。
3. 遇到校验报错别慌：报错信息已经写明了错误类型（missing required field / unknown meta key / typo / Duplicate ID）和涉及的应用名，照着改即可；不确定某个meta字段的含义时，查阅 pages/development.md 的 Meta Field Reference 表格。

总结

validate-json.py 虽然只有一个百余行的脚本，却示范了完整的质量防护思路：必填字段守结构、白名单守边界、纠错表守细节、按变体查重守业务规则，并且嵌入发布流水线作为第一道闸门。它证明了：对付"静默失败"最好的方式，是让错误在本地构建时就大声报错。