butler避坑：原理讲明白
butler避坑不能只靠记命令，很多问题出在没理解频道、路径、差量上传和权限。把背后的逻辑弄清楚，报错时就不会慌。下面按几个容易混淆的方面逐项对比，说点真能救急的话。
路径对比：文件夹不是压缩包思维
网页上传常让人习惯传 zip，但 butler push 更常见的是推一个构建文件夹。你给它的是本地目录，它会分析里面的文件，再上传到 itch.io 对应频道。butler避坑第一条：别把临时文件、工程源文件、缓存目录一股脑放进去。
正确做法是单独准备 dist、build 或 release 文件夹，只放玩家需要运行的内容。这样上传干净，也方便之后复查。
频道对比：win和win64别乱换
频道是 itch.io 页面上下载项的标识，也是 butler 更新的目标。第一次用“mygame:win”，下次改成“mygame:windows”，页面可能就多出一个下载项，而不是更新原来的内容。
所以频道名要固定，最好按平台简洁命名。团队协作时更要写进发布文档，不然甲传 win，乙传 pc，玩家看到会像进了杂货铺。
差量上传对比：快不是魔法
butler 的差量上传会比较文件变化，尽量只传改动部分。这就是它比反复传整包舒服的地方。但它不是魔法：如果你每次构建都把所有大文件重新打包成一个巨大 archive，哪怕只改一行配置，整体文件指纹也可能变化很大。
想让差量上传更有效，就尽量保持文件结构稳定，不要每次生成完全不同命名的大包。资源文件分散合理，更新效率通常更好。
权限对比：工具没错，账号可能错
很多报错看起来像网络或命令问题，实际是账号没有权限。butler login 登录的是当前机器上的 itch.io 账号，如果这个账号不是项目拥有者，也没有协作权限，就无法推送。
换电脑、换同事、换账号后，先用 butler logout 再 login，确认登录对象。别在一个终端里反复改命令，结果账号还是旧的。
版本对比：上传成功不等于说明清楚
butler 可以加版本信息，例如用 --userversion 标记给玩家看的版本号。没有版本说明，文件也能上传成功，但项目维护会变得含糊。
真正的 butler避坑，是把技术上传和发布沟通分开看：命令负责把文件送上去，页面说明负责告诉玩家这次修了什么。两件事都做，才算发布完整。
常见问题
butler上传后页面出现多个下载项怎么办？
多半是频道名不一致。检查每次 push 冒号后的频道，保留需要的下载项，删除或整理错误频道。
butler差量上传为什么还是很慢？
可能是大文件整体变化、网络不稳，或构建方式每次生成全新压缩包。尽量推稳定结构的文件夹。
butler提示没有权限怎么处理？
确认登录账号是否为项目所有者或协作者。必要时 logout 后重新 login，并检查 itch.io 项目权限。