企业官网建设流程全解析

• 桌面应用

本篇围绕 itch 仓库的 Flathub 发布文档 展开，说明 Linux 版 itch 桌面应用（Flatpak 包名io.itch.itch）如何从内部制品仓库（broth）自动同步到 Flathub、每次版本发布时需要人工完成的五步操作，以及当应用本身变更时哪些 manifest 文件需要手动改、如何用flatpak-builder在本地验证。读完本文，读者可以完整掌握 itch 应用在 Flathub 上的发布机制与日常维护操作。

包的基本形态：从 broth 下载 zip，用 zypak 包装

Flathub 上的包是io.itch.itch，由独立的 flathub 仓库（https://github.com/flathub/io.itch.itch）维护。它的构建方式可以概括为一句话：

从 broth 下载linux-amd64的 zip 包，用 zypak 和 Wine base runtime 包装起来，应用运行在 flatpak 沙箱内；更新来自 Flathub，而不是应用自带的更新器。

这句话里涉及三个关键事实，都可以在本仓库中找到对应证据：

• linux-amd64 zip 从哪来：本仓库的 release/deploy.js 在 CI 中把各平台构建产物推送到 itch.io 的 butler 通道，其中 Linux 版就是linux-amd64通道（./butler push ${artifactPath} itchio/itch:linux-amd64 --userversion=... --no-auto-wrap）。这些制品聚合在broth.itch.zone上——该地址同样出现在源码的 URL 常量定义（brothRepo: "https://broth.itch.zone"）中，应用运行时也用它作为 broth 仓库基址。
• zip 是怎么打出来的：release/packaging/do-package.js 展示了 Linux 包的产出过程——用@electron/packager把prefix/目录打成可移植 Electron 应用（asar: false、overwrite: true，输出到build/v<版本>/），再执行flipElectronFuses关掉RunAsNode、EnableNodeCliInspectArguments、EnableNodeOptionsEnvironmentVariable等“逃生门”，最后移入artifacts/linux-amd64目录。linux-amd64是 itch 在 Linux 上唯一的正式构建目标（getElectronOptions只处理os === "linux" && arch === "amd64"的组合）。
• 为什么 Flathub 版不走自带更新器：itch 的自带更新逻辑在 src/main/reactors/self-update.ts 中实现——通过itch-setup组件约每 2 小时检查一次（UPDATE_INTERVAL = 2 * 60 * 60 * 1000），由itch-setup --relaunch完成下载与重启。但在 flatpak 沙箱里，应用安装目录不可写、也没有提权手段，因此 Flathub 版必须放弃这条路，改由 Flathub 自身分发新版本——这正是文档中“updates come from Flathub, not from our own updater”的由来。另外从 src/main/broth/manager.ts 可以看到，常规组件包是["butler", "itch-setup"]，它们随包内运行，与 Flathub 层面的应用更新相互独立。

自动同步机制：Flathub 机器人监听 LATEST

itch 团队不向 Flathub 推送任何构建。同步完全由 Flathub 的 bot 完成：

1. bot 监听https://broth.itch.zone/itch/linux-amd64/LATEST这个“最新制品”指针；
2. 每当该地址对应的内容变化（即 itch 发布新版本、broth 通道更新后），bot 会在 flathub 仓库自动开一个 PR；
3. 该 PR 的内容是：更新io.itch.itch.yaml中的存档 URL 与 sha256，并在io.itch.itch.metainfo.xml里追加一条 release 记录。

换句话说，itch 侧唯一要做的“发布动作”就是先把新版本推到 itch.io 的 butler 通道（由release/deploy.js完成）；剩下拉取、校验、打包、上架全部由 Flathub 基础设施接管。这也解释了为什么 release/push-tag.js 里严格校验版本号格式为vX.Y.Z(-canary)?——版本号会一路流传到 metainfo 的 release 记录里，格式必须规整（例如v9999.0.0-canary这类 canary 版本的版本号生成逻辑见 release/common.js 中的getBuildTag/getBuildVersion）。

每次应用发布的五步操作清单

文档给出了逐版发布时的标准操作流程，完整继承如下：

1. 等 bot 的 PR 出现：broth 推送完成后，到https://github.com/flathub/io.itch.itch/pulls查看 bot 自动开的 PR，通常一天内会出现。
2. 等“Test build succeeded”评论：合并前可先用该评论中的测试仓库链接安装测试版尝鲜。
3. 核对 bot 追加的 metainfo release 记录：版本号不能带v前缀；如果缺少指向 GitHub release 的<url>，要手动补上。
4. 合并 PR：Flathub 会自行构建并发布，通常数小时内完成。
5. 关闭过期 PR：对于被跳过的版本（比如发版后又回滚、直接发新版覆盖了中间版本），把对应旧版本的 bot PR 关闭掉，避免它们被误合并。

第 3 步值得强调：metainfo 是 Flathub 展示给用户的元数据（描述、截图、release 历史），版本号带v前缀这类小问题不会导致构建失败，却会影响商店页展示，所以需要在合并前人工把关。

应用自身变更时：需要手动 PR 的内容

当 itch 应用本身的依赖或行为变化时，flathub 仓库中有三处需要人工提交 PR（bot 的自动 PR 只改版本号和 sha256，不会碰这些）：

finish-args一项与 itch 的核心业务直接相关：itch 作为游戏启动器，其本职就是拉起游戏进程。在 flatpak 沙箱里，游戏要么继承沙箱权限运行，要么经flatpak-spawn --sandbox进一步隔离——后一种路径要求宿主 flatpak 进程持有与org.freedesktop.Flatpak服务对话的权限，这就是文档强调--talk-name=org.freedesktop.Flatpak的原因。

本地验证 manifest 修改

改了 flathub 仓库的 manifest 之后，不必等 CI，可以在本地直接构建并安装验证：

flatpak-builder build-dir io.itch.itch.yaml --install --user --force-clean flatpak run io.itch.itch

参数含义：

• build-dir：flatpak-builder 的中间工作目录，缓存各 runtime 依赖，重复构建时不必重新拉取；
• --install：构建完成后直接安装到当前用户（--user安装，不需要 root 权限）；
• --user：装入用户级 flatpak 安装目录，便于随时flatpak uninstall清理；
• --force-clean：丢弃缓存的构建产物，确保从 manifest 干净地重新走一遍完整流程——验证finish-args或itch-run变更时尤其重要，避免上一次构建的残留干扰判断。

小结：一条“单向、低维护成本”的发布链

把上面的机制串起来，itch 在 Flathub 的发布链是单向的：git tag→ CI 打包（release/packaging/do-package.js）→ butler 推送到itchio/itch:linux-amd64（release/deploy.js）→ Flathub bot 发现LATEST变化 → 自动 PR（URL + sha256 + metainfo）→ 人工五步核对 → 合并 → Flathub 构建上架。itch 团队在这条链上只承担“推制品 + 合并前核对”两件事，版本分发、签名与上架全部交给 Flathub 基础设施；而当应用行为变化（权限、启动参数、商店页）时，则回到 flathub 仓库手动 PR 并可用flatpak-builder本地闭环验证。完整操作依据见 release/flathub.md。

• 桌面应用