nixpkgs 中 nexusmods-app 的 vendored 游戏数据:games.json 生成、缓存与构建集成机制解析
nixpkgs 中 nexusmods-app 的 vendored 游戏数据:games.json 生成、缓存与构建集成机制解析
本篇文章基于仓库文档 vendored/README.md 编写,并辅以 vendored/update.sh、vendored/game-ids.nix、vendored/games.json 与 package.nix 等源码文件进行纵深验证。
NexusMods.App 是一款游戏模组安装、创建与管理工具。在 nixpkgs 中,它的打包目录 pkgs/by-name/ne/nexusmods-app 下存放了一份构建期(build time)内置的游戏数据快照 games.json,本文即以该 vendored 数据为核心,完整讲解它在 Nix 打包体系中的价值定位、数据结构、自动生成脚本的运行原理、新游戏添加流程,以及它与上层构建/更新脚本的协作方式。读完后,你将掌握该包“运行时拉取 + 构建时缓存”双轨数据策略的完整实现,并能独立为 games.json 增补游戏或维护整个更新链路。
一、背景:为什么一份游戏列表会被“vendored”进 nixpkgs
NexusMods.App 会在运行时从 NexusMods 官方接口获取游戏元数据(游戏名、ID、下载量等)。然而在 nixpkgs 的打包中,vendored/README.md 明确说明:这些数据同时被包含在构建产物中,原因有二:
- 让测试能够针对真实数据运行 —— 单元/集成测试不再依赖网络,可以直接使用与线上一致的完整游戏信息做断言;
- 充当缓存数据,加速应用首次启动 —— 首次运行时不必等待完整的在线数据下载,本地即有一份可用的基础数据集。
这份 games.json 并非“必须包含全部游戏”。文档给出的边界是:“理想情况下应包含该版本 NexusMods.App 所支持的全部游戏”,这样首次运行的缓存才更有实用价值;而测试套件所引用的游戏则属于硬性底线(game-ids.nix 注释中明确写道“除测试套件引用的游戏外,不必包含所有游戏”)。
二、vendored 目录的组成
pkgs/by-name/ne/nexusmods-app/vendored/ 下共有 4 个文件,分工如下:
| 文件 | 作用 |
|---|---|
| README.md | 说明 vendored 策略的目的与维护方式 |
| game-ids.nix | 手工维护的游戏白名单(游戏名 → ID 的 attrset) |
| games.json | 由脚本生成并提交入库的数据快照 |
| update.sh | 负责拉取、过滤、校验并落盘 games.json 的生成器 |
其中 games.json 与 game-ids.nix 是一生成、一约束的关系:前者是产物,后者是决定“哪些游戏进入产物”的声明式白名单。
三、games.json 数据结构解析
以仓库中实际的 games.json 为例,它是一份按 id 升序排列的 JSON 数组,当前包含 5 款游戏:Stardew Valley、Skyrim Special Edition、Mount & Blade II: Bannerlord、Cyberpunk 2077、Baldur's Gate 3。每个条目携带以下字段:
| 字段 | 含义 | 示例值(Baldur's Gate 3) |
|---|---|---|
id |
NexusMods 游戏 ID,白名单匹配键 | 3474 |
name |
游戏显示名 | Baldur's Gate 3 |
name_lower |
小写化名称,供模糊匹配 | baldur's gate 3 |
forum_url |
论坛讨论区地址 | 对应游戏论坛页 |
nexusmods_url |
游戏模组主页 | 对应 nexusmods 域名页 |
genre |
游戏类型 | RPG |
file_count |
已收录文件数 | 107598 |
downloads |
累计下载量 | 366648874 |
domain_name |
站内域名标识 | baldursgate3 |
approved_date |
收录时间戳(Unix 秒) | 1602863114 |
mods |
模组数量 | 15345 |
collections |
合集数量 | 1725 |
这些字段与 NexusMods 官方数据接口(托管于 data.nexusmods.com 的 nexus-data/games.json)保持同构,因此生成脚本可以直接对官方数据进行“按 ID 过滤 + 排序”而无需重新建模。
四、生成脚本 update.sh 的工作原理
vendored/update.sh 是一个基于 nix-shell 的 bash 脚本,依赖 bash curl jq。其执行流水线分四步:
第一步:读取白名单 ID 列表
脚本先通过 nix-instantiate 求值 game-ids.nix,把 attrset 的值(即所有游戏 ID)提取为 JSON 数组:
ids=$(
nix-instantiate --eval --json \
--argstr file "$dir"/game-ids.nix \
--expr '{file}: builtins.attrValues (import file)'
)
builtins.attrValues 返回 attrset 的所有值,即 [3474 3333 3174 1704 1303] 这样的 ID 数组(顺序取决于 attrset 内部求值顺序,但后续有排序步骤兜底)。
第二步:拉取官方数据并按白名单过滤
curl "$url" --silent --show-error --location |
jq --argjson ids "$ids" \
'map(select( .id | IN($ids[]) )) | sort_by(.id)' \
>"$tmp"
curl -L 跟随重定向,jq 先按 id ∈ 白名单 过滤,再按 id 升序排序后写入临时文件。注意这里并没有修改任何字段,games.json 中每个游戏的其余字段(下载量、模组数等)都直接继承自官方接口的实时数据——这正是“新增游戏”时旧数据也会被顺带刷新的原因。
第三步:Nix 层校验数据一致性
这是脚本最巧妙的一步:用 nix-instantiate 以 strict 模式求值一段校验表达式,断言每个游戏条目的 id 与 game-ids.nix 中以名字为键记录的 ID 完全一致:
nix-instantiate --eval --strict \
--argstr idsNix "$dir"/game-ids.nix \
--argstr gamesJson "$tmp" \
--expr '{ ... }:
let
ids = import idsNix;
games = lib.importJSON gamesJson;
in
lib.forEach games (
{ id, name, ... }:
lib.throwIfNot
(id == ids.${name})
"${name}: id ${toString id} does not match ${toString ids.${name}}"
null
)' >/dev/null
具体语义是:对结果中的每个游戏,取其 name,去 game-ids.nix 中查对应 ID,若与接口返回的 id 不符则抛出 "<name>: id <实际> does not match <期望>" 错误并中断脚本。这条校验有效防止了“白名单中名字与 ID 错配”“接口字段结构变化”等隐患,同时验证了 jq 过滤后的结果与声明式白名单严格对应。
第四步:原子落盘
mv --force "$tmp" "$dir"/games.json
生成过程全程使用 mktemp 临时文件,校验通过后才 mv 覆盖正式文件,避免写坏仓库中的 games.json。脚本整体以 set -eu -o pipefail 开启严格模式,任何一步失败都会以非零退出码终止,保证不会落盘半成品。
五、如何向 games.json 添加一款新游戏
vendored/README.md 给出了标准四步流程:
- 查 ID:到 NexusMods 的数据接口(
nexus-data/games.json)中找到目标游戏的name与id; - 写白名单:把
name与id加入 game-ids.nix,例如:
{
# keep-sorted start case=no numeric=yes
"Baldur's Gate 3" = 3474;
"Cyberpunk 2077" = 3333;
"Mount & Blade II: Bannerlord" = 3174;
"Skyrim Special Edition" = 1704;
"Stardew Valley" = 1303;
# keep-sorted end
}
注意文件内有 # keep-sorted 注释标记,表明该 attrset 由 keep-sorted 工具按“不区分大小写、数值不作为排序依据”的规则维护,新增条目需保持字典序。
- 运行生成脚本:执行
pkgs/by-name/ne/nexusmods-app/vendored/update.sh,它会重新拉取官方数据、过滤出新白名单集合、执行一致性校验并覆盖games.json; - 提交结果:将更新后的
games.json提交入库。
关于提交粒度的提醒:由于脚本会“顺带刷新白名单中所有游戏的元数据”(下载量、模组数等实时字段都会变化),README 特别建议使用 git add --patch 将改动拆成两个独立提交——一个只包含新游戏条目,另一个包含既有数据的刷新,便于代码审查与回滚定位。
六、构建期集成:package.nix 中的替换逻辑
vendored 数据之所以能“参与构建”,关键在于 package.nix 的 postPatch 阶段对上游 csproj 构建规格做了替换:
postPatch = ''
...
# Use a vendored version of the nexus API's games.json data
substituteInPlace src/NexusMods.Networking.NexusWebApi/NexusMods.Networking.NexusWebApi.csproj \
--replace-fail '$(BaseIntermediateOutputPath)games.json' ${./vendored/games.json}
'';
这条 substituteInPlace 把上游 NexusMods.Networking.NexusWebApi 项目构建流程中原本会自行下载/生成的 $(BaseIntermediateOutputPath)games.json 替换为 nixpkgs 仓库内的 vendored 副本,从而:
- 离线可构建:构建期不再需要访问外部数据源;
- 可复现:产物中的游戏数据由仓库锁定版本决定,不随线上接口波动;
- 测试可用真实数据:
NexusMods.Networking.NexusWebApi相关的测试可直接读取这份快照(这正是 README 中“允许测试针对真实数据运行”的实现落点)。
与之配套的还有同阶段对 game_hashes_db.zip 的固定(指向 game-hashes/default.nix 中 fetchurl 的 pin 版本),以及对 buildDate.txt 的固定以提升构建可复现性——三者共同构成该包“构建期数据本地化”的完整策略。
七、数据过大时的回退方案
README 同时预见了另一种边界情况:如果白名单无限膨胀导致 games.json 体积过大,文档给出的处置路径是:
- 修改
csproj构建规格,使games.json不再参与构建期打包(即撤销第六节的替换逻辑,恢复运行时拉取); - 相应修补或禁用任何依赖这份 vendored 数据的测试。
这一设计体现了该 vendored 策略的“软性”定位:它本质上是一个可随时摘除的性能与测试优化,而非功能上的硬依赖。只要把数据来源退回运行时接口,应用依然可以正常工作。
八、与顶层更新脚本的编排关系
vended 的生成并不是孤立存在的。仓库根目录的 update.sh 以 nix-shell 驱动、依赖 bash nix-update,将整个包的更新编排为三步:
# 1. 更新 vendored 文件(即 games.json)
"$dir"/vendored/update.sh
# 2. 更新 game_hashes_db(通过 gh 查询 Nexus-Mods/game-hashes 最新 release 并重算 hash)
UPDATE_NIX_ATTR_PATH="$UPDATE_NIX_ATTR_PATH.gameHashes" \
"$dir"/game-hashes/update.sh
# 3. 更新包版本(读取 meta.homepage 后调用 nix-update)
nix-update --url "$url"
也就是说,维护者只要运行一次顶层脚本,games.json、game_hashes_db 与包版本会按序同步刷新。其中 game-hashes/update.sh 走的是另一条链路:通过 gh CLI 查询上游 release、nix-prefetch-url 下载并计算 SRI hash,最后 update-source-version 写回 game-hashes/default.nix。两套 vendored 数据(游戏元数据 + 文件哈希库)分别服务应用的不同能力,但共享“构建期本地化、运行时增强”的同一设计哲学。
九、小结
围绕一份看似简单的 games.json,nixpkgs 的 nexusmods-app 包构建了一整套闭环:
- 声明式白名单(game-ids.nix)控制数据范围;
- 可重跑生成器(vendored/update.sh)完成拉取 → 过滤 → Nix 校验 → 落盘;
- 构建期替换(package.nix 的
postPatch)保证离线构建、可复现产物与真实数据测试; - 顶层编排(update.sh)统一维护数据与版本;
- 软性回退(patch csproj / 禁用相关测试)为未来体积增长预留了出口。
这一模式对任何“运行时依赖外部 API 数据、又希望在 Nix 构建中享受缓存与测试便利”的打包场景,都是一份值得借鉴的参考实现。