技能介绍

要解决的问题

itch.io 的上传流程看似简单，实际有不少坑。手动拖拽文件到网页每次都是全量上传，补丁包巨大；把安装程序（.exe、.msi）推上去会破坏 itch app 的自动更新与补丁机制；HTML5 游戏推上去却显示为下载文件，需要手动在页面改两处设置；渠道名拼写不一致会凭空多出重复的下载入口。这些细节散落在各处文档里，出错时排查成本不低。

核心工作方式

这个技能把发布流程收敛为一个命令：butler push。上传通过 itch.io 官方命令行工具 butler 完成，首次推送整个构建目录，之后同一渠道的推送只上传与上一版的差异，更新包体积取决于实际变更量，而不是重新打包整个压缩包。

关键步骤：

建页面：在 itch.io 创建项目页，原生构建选 Downloadable，网页游戏选 HTML，上线前保持 Draft。
装工具并登录：本地用 butler login 走浏览器授权，CI 环境改用 BUTLER_API_KEY。
准备便携构建目录：只放玩家实际运行的文件，推目录或单个 .zip，不要推安装包，也不要预先压成多层压缩包。
推送渠道：butler push <folder> <user>/<game>:<channel>，渠道名用 kebab-case 小写，决定页面上的平台标签。
校验与预览：butler status 查看渠道和构建，butler push-preview 在真正推送前先看变更内容。
版本控制：用 --userversion 或 --userversion-file 显式指定版本号，供玩家和更新 API 读取。

适用边界与注意点

这个技能只负责上传这一步。要发 Steam 版本请用 steam-publish；要做 jam 的玩法规划请用 game-jam；要构建游戏本身需要引擎类技能。几个高频陷阱值得记住：--hidden 只对新建渠道生效，对已有渠道使用会报错；windows 和 win-final 是两个不同渠道，会生成两份下载；未压缩总大小超过 30 GB 会被 itch.io 拒绝；CI 日志里泄露的 BUTLER_API_KEY 必须立刻吊销。