itch-publish

itch.io 发布（butler）

将构建版本发布到 itch.io 页面并保持更新。页面在浏览器中创建；所有上传都通过 butler（itch.io 的命令行工具）完成，你只需记住一个命令：butler push。butler 会与上一个构建版本进行比较，只上传发生变化的内容。有关 CI/CD 和标志的详细信息，请参阅 references/butler-ci.md。

适用场景

• 创建或更新 itch.io 项目页面、安装或登录 butler、使用 butler push 上传构建版本、选择频道名称、对上传版本进行版本管理，或向 itch.io 发布游戏果酱、演示版或正式版构建时使用。
• 触发词：butler push、butler login、频道、.itch.toml、“在 itch 上发布”、“上传到 itch”。

不适用场景： 在 Steam 上发布（使用 steam-publish）；规划游戏果酱的范围/计划（使用 game-jam——此技能仅涵盖上传操作）；构建游戏本身（使用引擎技能）。

核心工作流

1. 创建项目页面，网址为 itch.io/game/new。设置 Kind of project：原生构建版本选择 Downloadable，可在浏览器中游玩的游戏选择 HTML（网页构建版本必须选择此项——参见“注意事项”）。设置定价和可见性（准备就绪前保持为草稿）。
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. 频道命名决定平台标签（短横线命名法，全小写）

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 游戏显示为下载内容。 需要设置两个选项：将页面的 Kind 设为 HTML，并在首次推送后于 Edit game 页面为频道添加 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 — 大多数游戏创作马拉松都托管在 itch.io 上；此技能负责上传步骤。
• prototype-fast — 在 Draft/受限的 itch 页面分享早期原型，以便进行试玩测试。