itch.io 发布（butler）

将构建上传到 itch.io 页面并保持更新。页面在浏览器中创建；所有上传都通过 butler 进行，这是 itch.io 的命令行工具，你只需使用一条命令即可：butler push。butler 会与前一个构建进行差异比较，并只上传发生变化的内容。深入的 CI/CD 和标志详情位于 references/butler-ci.md。

何时使用

• 在创建/更新 itch.io 项目页面、安装或登录 butler、使用 butler push 上传构建、选择频道名称、版本化上传，或将 jam/demo/release 构建推送到 itch.io 时使用。
• 触发条件：butler push、butler login、channels、.itch.toml、"publish on itch"、"upload to itch"。

何时不使用： 在 Steam 上发布（使用 steam-publish）；游戏 jam 的*范围/规划*（使用 game-jam — 此技能只处理上传机制）；构建游戏本身（引擎技能）。

核心工作流

1. 在 itch.io/game/new 创建项目页面。设置 Kind of project：对于原生构建保持 *Downloadable*，或为可在浏览器中游玩的游戏选择 HTML（这是 Web 构建所必需的 — 见陷阱）。设置价格/可见性（在准备就绪前保持 Draft）。
2. 安装 butler 并登录。 从 itchio.itch.io/butler 下载，将其添加到 PATH，然后运行 butler login（会打开浏览器进行授权）。使用 butler version 验证。对于 CI，请改用 BUTLER_API_KEY — 见参考。
3. 准备一个可移植构建文件夹 — 玩家实际运行的准确文件，不要有多余内容。推送一个 文件夹（或该文件夹的单个 .zip），不要是安装程序，也不要是预先压缩的归档套归档（会损害补丁；见陷阱）。
4. 推送到频道： butler push <dir> <user>/<game>:<channel>。频道名称决定平台标签（见模式）。第一次推送会上传全部内容；之后向同一频道推送只会上传差异。
5. 如果频道未被正确自动打标签，请在 *Edit game* 页面上设置平台/HTML 标签，然后 Save。对于浏览器游戏，还要将页面切换为 HTML，并将频道标记为 *playable in browser*。
6. 为构建设置版本（可选但推荐）：--userversion 1.2.0 或 --userversion-file build.txt，以便你控制玩家和更新 API 看到的版本字符串。
7. 稍后更新，方法是再次推送到*同一*频道。使用 butler status <user>/<game> 查看频道/构建，并使用 butler push-preview 在发送前查看推送会更改什么。

模式

1. 只需这一个命令 — butler push

# butler push <directory-or-zip> <user>/<game>:<channel>
butler push ./build/windows leafy/my-game:windows
butler push ./build/mac     leafy/my-game:osx
butler push ./build/linux   leafy/my-game:linux
butler push ./web           leafy/my-game:html   # browser build (also set page Kind = HTML)

2. 频道命名控制平台标签（kebab-case，小写）

Substring in channel name -> auto-applied tag:
  win / windows  -> Windows        linux -> Linux
  mac / osx      -> macOS          android -> Android
Multiple platforms in one channel are allowed: e.g. a Java jar:
  butler push ./jar leafy/my-game:win-linux-mac
Convention: lowercase words separated by dashes (windows-beta, osx-demo, soundtrack).
Tags are only the INITIAL guess — fix them anytime on the Edit game page (then Save).

3. 版本、验证与预览

butler version                              # print version; confirms install + PATH
butler login                                # authorize this machine (opens browser)

# Set an explicit version string instead of itch's auto-incrementing integer:
butler push ./build leafy/my-game:windows --userversion 1.2.0
butler push ./build leafy/my-game:windows --userversion-file build_number.txt

butler status leafy/my-game                 # list channels + latest builds/versions
butler push-preview ./build leafy/my-game:windows   # NEW/MODIFIED/DELETED/SAME, uploads nothing

4. 首次、隐藏与过滤推送

# Hide a brand-new channel from the page until you're ready (NEW channels only):
butler push ./build leafy/my-game:windows-beta --hidden

# Exclude files from the upload without copying the folder (--ignore is repeatable):
butler push ./build leafy/my-game:windows --ignore '*.pdb' --ignore '*.dSYM'

# Preview exactly what would be sent, without sending it:
butler push ./build leafy/my-game:windows --dry-run

陷阱

• 推送安装程序。 itch.io 会为*可移植*构建打补丁；安装程序（.exe/.msi）会使补丁失效，并使 itch 应用的自动更新失效，还可能需要玩家没有的管理员权限。改为推送已解包的、可运行的文件夹。
• 预压缩构建。 推送高度压缩的归档（或归档套归档）会使补丁变得巨大 — 微小更改都会重写整个压缩块。推送未压缩文件；itch.io 会在其服务端压缩。
• 只包含一个 .zip 的文件夹。 butler 会自动解压并推送其内容（以避免“zip 套 zip”）。只有当你确实希望将该 zip 作为一个不透明文件上传时，才传递 --no-auto-unzip。
• HTML5 游戏显示为下载。 需要两个开关：第一次推送后，在 *Edit game* 页面将页面 Kind 设置为 *HTML*，并将频道标记为 *playable in browser* — 两者都不会从频道名称自动完成。
• 对现有频道使用 --hidden 会报错。 它仅适用于推送*创建*新频道时。之后可从 *Edit game* 取消隐藏。
• 频道拼写错误会产生重复槽位。 windows 和 win-final 是不同频道，会创建单独的下载。事先确定频道名称并复用它们。
• 30 GB 上限。 itch.io 会拒绝总*未压缩*大小超过 30 GB 的构建。
• CI 日志中的密钥。 在公开日志中打印的 BUTLER_API_KEY 已经泄露 — 请立即在 API keys 页面撤销它。有关安全的 CI 用法，见参考。

参考

• 对于使用 BUTLER_API_KEY 的 CI/CD（GitHub Actions/GitLab）、通过 broth 自动安装、完整标志列表以及更新检查 API，请阅读 references/butler-ci.md。
• 主要文档：butler 手册 — itch.io/docs/butler（安装、登录、推送）。

相关技能

• steam-publish — 通过 SteamPipe 在 Steam 上发布同一游戏（通常与 itch.io 一起发布）。
• game-jam — 大多数 jam 都在 itch.io 上托管；此技能处理上传步骤。
• prototype-fast — 在 Draft/受限的 itch 页面上分享早期原型以进行试玩。