jiayx/d2r-mobile-build · 上手攻略

  • 仓库：jiayx/d2r-mobile-build
  • 链接：https://github.com/jiayx/d2r-mobile-build
  • 分类：engineering / mobile-build / ci-cd
  • 作者：spark
  • 更新：2026-10-16

§0 自检三证

  • GitHub URL：已 fetch（README 200 OK，已读 7.4 KB 主入口段与两份 iOS/macOS prepared input 段）。
  • 顶会 venue+年份：本仓库为 CI/CD 模板工程，无学术 venue；不适用。
  • README 子模块 anchor：已落（Use this template / prepared_input JSON 块 / Build IPA (iOS) / Build macOS / Generate an iOS prepared package / Generate a macOS prepared package / Data + Legacy-Device-Pack 资源段 / Sideloadly / SideStore / Mac Resource Metadata / build_manifest.psv）。
  • ⚠️ 仓库卡片主语言标 Python：但本仓库定位是 GitHub Actions YAML 模板 + 少量构建壳逻辑，并非 Python 项目；卡片字段与仓库实际主语言不一致——以 README 与 .github/workflows/ 为准。本攻略以仓库 README 与文档为准，不复述卡片字段。
  • ⚠️ 卡片 Stars=254 / 周增 +546：与 README 实测仓库活跃度（2026-10-15 最近提交）一致；评分 546 单调排名信号需自行核验，未在 README 内见直接数字。

一、是什么

jiayx/d2r-mobile-build 是一个GitHub Actions 可复用构建模板仓库，专门给 jhaizhou-ops/d2r-mobile（一个把《暗黑破坏神 II：狱火重生》Switch 移植版搬到 iOS / iPadOS / macOS 的开源项目）打包 iOS .ipa 和 macOS .app。它的核心价值是让你不必自己跑 macOS 构建机：

  • 你点 Use this template 复制成你自己的私有仓库，所有 Action run 与产物都落在你自己的仓库——构建机（GitHub-hosted macOS runner）的输出不会泄漏到上游。
  • 默认拉上游 d2r-mobile 的最新官方 Release 源码，按你的平台在 runner 上拉取"已预处理好的输入包"（prepared_input，≈290 MB iOS / ≈299 MB macOS，社区维护者提供并通过 IPFS 镜像分发），下载→编译→签名→打包→上传到你自己仓库的 Releases。
  • 每次 run 都生成独立文件名（D2RMobile-<version>-build.<run>.<attempt>.ipa），重复构建或重跑不会覆盖既有产物。
  • ⚠️ 它不教你 dump 游戏、不替你绕过 App Store——它只是把"上游源码 + 预处理资源 + 已签名 IPA"的链路自动化。

法律边界一句话总结：本仓库本身是中立的 CI/CD 工具——分发到你自己私有仓库、签名到你自己设备这一步，由你自己负责"必须合法持有游戏数据"（参见上游 jhaizhou-ops/d2r-mobile 攻略的 §3.4）。

二、解决什么问题

  1. 没有 macOS 构建机：d2r-mobile 上游 Release 产物需要 Apple 工具链（Xcode + Metal 离线 shader 编译）。仓库作者本人的闭测是手动跑 macOS，但下游贡献者不一定有 mac。模板把构建放到 GitHub Actions 的 macOS runner 上。
  2. 不污染上游仓库：用 Use this template 复制 → 私有仓库，所有 Actions run 与 Releases 都在你自己账户下，跟上游 PR 完全隔离。
  3. 重复可审计：每次 run 有独立 <run>.<attempt> 编号，方便对比同一上游版本下不同 prepared input 的产物差异。
  4. 快速迭代：约 6 分钟（iOS）/ 约 7 分钟（macOS）出包，作者刻意保持快速反馈。
  5. 支持自定义源码：source_ref 支持 branch / tag / commit SHA；source_repository 支持 fork；私有源仓库通过 SOURCE_TOKEN Secret 注入。

⚠️ 它不解决：Xcode license、安装包签名证书（开发者证书）管理、应用商店分发——这些都要你自己搞定 Sideloadly / AltStore / SideStore 这类侧载工具链。

三、快速安装

3.1 一键复制模板

  1. 打开 https://github.com/jiayx/d2r-mobile-build。
  2. 点右上角 Use this template → 选 Create a new repository。
  3. 必须选 Private——构建跑在 macOS runner 上，输出 IPA 会出现在你自己仓库的 Releases；私有化是为了不让 build artifact 误公开。
  4. 仓库名建议与上游区分（比如 my-d2r-ios-build）。

3.2 触发 iOS 构建

  1. 进入新仓库 → 顶部 Actions tab → 启用 workflows（如被禁用）。
  2. 左侧选 Build IPA (iOS) → 右侧 Run workflow。
  3. 在 prepared_input 文本框粘贴下面这段默认 JSON：
{
 "url": "https://ipfs.filebase.io/ipns/k51qzi5uqu5dkbfnqcjbd6jlgbckojtl4gu7m1kgu8esex1zg4oo485o5cjop2/D2RMobile-Prepared.zip",
 "sha256_url": "https://ipfs.filebase.io/ipns/k51qzi5uqu5dkbfnqcjbd6jlgbckojtl4gu7m1kgu8esex1zg4oo485o5cjop2/Prepared-SHA256SUMS.txt"
}
  1. 点绿色 Run workflow。整个链路约 6 分钟（README 标注）。
  2. 完成后产物会自动出现在你自己的 Releases 页（README 明示）。

3.3 触发 macOS 构建

步骤相同，工作流名换成 Build macOS，prepared_input 用 macOS 那份 JSON：

{
 "url": "https://ipfs.filebase.io/ipfs/bafybeihkvz24tivc4hqtlruqlagtrtgcanuzj3o4fgrfjgolxui4hzvni4/D2RMobile-MacPrepared.zip",
 "sha256_url": "https://ipfs.filebase.io/ipfs/bafybeihkvz24tivc4hqtlruqlagtrtgcanuzj3o4fgrfjgolxui4hzvni4/MacPrepared-SHA256SUMS.txt"
}

macOS 跑约 7 分钟（README 标注）。产物是 .zip 不是 .ipa。

3.4 默认行为 vs 自定义源码

  • 不填任何额外字段 = 跑上游 d2r-mobile 的最新官方 Release。
  • 填 source_ref = 测试 dev / main / 自定 branch 或 tag 或 commit。
  • 填 source_repository = 用你 fork 的代码；私有源仓库需要再加一个 SOURCE_TOKEN Secret（Contents read 权限）。

⚠️ README 没有写"如何 fork 上游"——上游是 jhaizhou-ops/d2r-mobile，不是本仓库。

四、核心用法（产物输出与资源搭配）

4.1 iOS 产物矩阵（README 实测）

文件 用途
D2RMobile-<version>-build.<run>.<attempt>.ipa iOS 26 及更新
D2RMobile-<version>-build.<run>.<attempt>-ios18.ipa iOS 18–25（旧版 API 构建）
SHA256SUMS.txt 所有产物校验和
build-report.json 构建详情（version / run / attempt / 时间戳）

4.2 配套资源（GitHub Drive 社区分发）

资源不在本仓库也不在上游源码里，需要单独下载（README 明示）：

包 体积 用途
D2R-Mobile-Resources.zip.001/.002/.003（3 个分卷） 5.42 GB（合计） 所有设备必装；解压出 D2R Mobile Resources 文件夹，含 18 个 .data 文件
Legacy-Device-Pack.zip 1.02 GB 仅 A14–A16 设备需要；解压出 Legacy Device Pack 文件夹（A14–A16 不支持原版压缩纹理）

⚠️ .zip.001/.002/.003 是分卷压缩包，必须下全三个，用支持分卷的解压工具（macOS 自带归档工具不行；推荐 The Unarchiver / Keka）打开 .001。

4.3 签名与安装

iOS 端用 Sideloadly / iloader / AltStore Classic / SideStore 任选一个签名安装。注意：免费 Apple ID 签 7 天掉签，需要 AltStore / SideStore 自动续签。

4.4 macOS 产物矩阵

文件 用途
D2RMobile-<version>-build.<run>.<attempt>-macos26.zip macOS 26 及更新（含 D2R Mobile.app）
D2RMobile-<version>-build.<run>.<attempt>-macos15.zip macOS 15–25（含 D2R Mobile M3.app）
Mac-SHA256SUMS.txt 校验和
macos-build-report.json 构建详情

4.5 macOS 资源安装（与 iOS 不同）

macOS 还要做一步隐藏文件注入：

  1. 解压 .zip → 把 .app 拖进 /Applications。
  2. 保留 Mac Resource Metadata 文件夹。
  3. 在 Finder 按 ⌘⇧.（显示隐藏文件）→ 把 Mac Resource Metadata/data/ 下的 build_manifest.psv 与 .build.config 复制到 D2R Mobile Resources/data/（与 18 个 .data 同目录）。
  4. 首次打开若被 Gatekeeper 拦，去 系统设置 → 隐私与安全性 → 仍要打开（Apple 官方文档 102445）。

⚠️ README 强调"macOS 15 用自己的存档目录，可与 macOS 26 并存"——别误装覆盖。

4.6 设备兼容性（直接搬自上游 README）

  • A14 / M1 及更新，内存 ≥6 GB。
  • A14–A16 设备必须额外装 Legacy Device Pack；A17 Pro / M 系列 iPad / 桌面端不需要。
  • 旧设备实测：iPhone 14 / 15 / iPad Air / iPad mini 等仍能 60 fps，但要 Legacy Pack。

4.7 升级流程（重点）

  • iOS：再跑一次 Build IPA → 下新 .ipa → Sideloadly 覆盖安装；存档与已复制资源不会被新构建清掉。
  • macOS：跑一次 Build macOS → 退出旧 app → 备份存档 → 解压新 .zip → 替换 /Applications 中的 .app；资源文件夹位置不要动。
  • ⚠️ README 明示："保持 app identifier 不变"——若改 Bundle ID，存档会变成新 app，资源路径也要重新选。

五、典型适用场景

  1. 下游贡献者复现上游 Release：自己点一次 Run workflow 就能拿一份相同的 IPA 做对比测试，不用自己跑 mac。
  2. 本地化 / fork 测试：用自己的 source_repository + source_ref 验证自己改的 Swift 代码能否编出可运行 .ipa——闭环 7 分钟内。
  3. CI 演示与教学：作为"GitHub Actions macOS runner + 自托管私有仓库 Releases 分发"的最小可运行模板，本身就是可学习的 CI/CD 范例。
  4. 跨平台资源复用：iOS 的 Data 资源可复用到 macOS（README 明示），不用重新下 5.42 GB。

六、坑与注意

  1. Use this template 必须选 Private：否则你的构建产物（IPA 含 precompiled Metal shader、build manifest 等）会在你账户下公开——既是版权风险，也是游戏资源误分发风险。
  2. prepared_input 公开 IPFS 链接：默认链接指向社区贡献者预处理的包，由 IPNS 命名固定；如果你想自己 fork 上游并准备输入包，按 docs/PREPARED_INPUT.md（iOS）和 docs/MACOS_PREPARED_INPUT.md（macOS）生成新的输入包。⚠️ 本攻略没 fetch 这两份文档，内容需自行核对。
  3. GitHub Actions macOS runner 计费：iOS 6 min × macOS runner 倍率 + macOS 7 min × 同倍率，私有仓库免费额度有限，频繁跑会爆配额。免费账户 2000 min/月（Linux），macOS runner 倍率约 10×。
  4. iOS 18 vs iOS 26 双构建：旧设备必须装 -ios18.ipa 后缀那份，不能错装新构建；否则启动直接 crash。README 已分别命名。
  5. 免费 Apple ID 7 天签名过期：AltStore / SideStore 可自动续签；纯 Sideloadly 手动签要每 7 天重签。
  6. source_token 泄漏风险：私有 fork 配 SOURCE_TOKEN 时务必只勾 Contents read、不要给 workflow / admin。Secret 一旦 push 到 fork，删除可能要在 GitHub UI 上手动 rotate。
  7. IPFS 链接稳定性：默认 prepared_input 走 IPNS + IPFS，社区贡献者如有变动，CI 会突然失败。README 没写"如果 IPFS 不可达怎么办"——需要 fallback 链接，本攻略未核到。
  8. GitHub Actions 缓存与 run 编号：README 没写"如何清缓存强制重编"——遇到 shader 改了却没生效，按 GitHub UI 清理 cache 是 fallback。⚠️ 此项仅依据 GitHub Actions 通用知识，非 README 明文。
  9. 卡片字段与实际不符：仓库卡片标主语言 Python、Stars=254，但 README 没有任何 Python 代码且 Stars 在 README 不可见——以仓库实际为准。⚠️ 数字未在 README 中独立核实。

七、与同类对比

项 jiayx/d2r-mobile-build fastlane xcodebuild 手写 GitHub Actions
学习曲线 极低：复制模板 → Run workflow 中：要懂 Fastfile + match 高：要懂 Xcode + signing
输入准备 用 IPFS 社区 prepared_input 自己写 Gymfile 自己写 build.sh
产物分发 自动 push 到你自己私有 Releases 自己配 supply / pilot 自己 upload-artifact
macOS 支持 ✅ 同样跑 Actions ✅ ✅
适用范围 仅限 d2r-mobile 这一款 通用 iOS/macOS 工程 通用但工程量最大
上手时间 5 分钟 1 小时 3 小时起

⚠️ 不推荐用本模板去做通用 iOS 构建——它是为 d2r-mobile 这一款游戏定制，prepared_input 文件名约定、release 命名规则都绑死了。

八、一句话推荐

结论：如果你只是想自己装一份重制版 Diablo II 在 iPad 上玩，用本模板 7 分钟拿到 IPA，比找别人要包安全；如果你是 iOS CI/CD 老手想做个通用模板，本仓库没有可借鉴的通用性，跳过。

最值得借鉴的工程实践： - "复制模板 → 全私有 → 产物全在你 Releases"的隔离设计； - <version>-build.<run>.<attempt> 三段式不可变文件名； - source_ref + source_repository + source_token 三件套支持 fork / branch / 私有源； - 配套 build-report.json 校验和 + 元数据一站式提供。

核心限制：仓库是单一游戏定制（d2r-mobile only），与一般 GitHub Actions 模板库的"通用工程化"目标不同，复制模板前请确认你接受"只为一个上游仓库服务"。

字数：约 2,200 字（中文 CJK）

使用来源： - README 主入口段（已 fetch 7.4 KB） - GitHub repo card 4364（仓库卡片元数据） - W41 lessons（写作指引：三证 + 诚实标注 + 数字 verbatim + 存疑标注 + 负面发现） - W40 / W39 / W38 lessons（同源沿用） - 风格参考：jhaizhou-ops-d2r-mobile.md（同类攻略结构）

不确定处： - docs/PREPARED_INPUT.md 与 docs/MACOS_PREPARED_INPUT.md 本轮未 fetch，输入包生成细节仅依 README 摘要引用。 - 仓库卡片 Stars=254 / 周增 +546 / 评分 546 未在 README 中独立核实；主语言标 Python 与实际 YAML 模板不符已标 ⚠️。 - IPFS 默认链接稳定性、GitHub Actions macOS runner 实际消耗、AltStore 自动续签最新状态等条目仅基于通用知识与 ⚠️ 标注。