itch-publish

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

itch.io Publish (butler)

itch.io 发布（butler）

Get a build onto an itch.io page and keep it updated. The page is created in the browser; all uploads go through butler, itch.io's command-line tool, with one command you'll use forever:

butler push

. butler diffs against the previous build and uploads only what changed. Deep CI/CD and flag detail lives in

references/butler-ci.md

将游戏构建版本上传到itch.io页面并保持更新。页面需在浏览器中创建；所有上传操作都通过itch.io的命令行工具butler完成，你将永远使用这一条命令：

butler push

。butler会与上一个构建版本进行差异对比，仅上传变更的内容。详细的CI/CD和参数说明请查看

references/butler-ci.md

。

When to use

使用场景

Use when creating/updating an itch.io project page, installing or logging in to butler, uploading a build with
```
butler push
```
, choosing channel names, versioning uploads, or shipping a jam/demo/release build to itch.io.
Triggers:
```
butler push
```
,
```
butler login
```
, channels,
```
.itch.toml
```
, "publish on itch", "upload to itch".

When not to use: publishing on Steam (use

steam-publish

); jam scope/planning (use

game-jam

— this skill is only the upload mechanics); building the game itself (engine skills).

适用于创建/更新itch.io项目页面、安装或登录butler、使用
```
butler push
```
上传构建版本、选择渠道名称、版本化上传，或是将游戏jam版本/演示版/正式版发布到itch.io的场景。
触发关键词：
```
butler push
```
、
```
butler login
```
、渠道、
```
.itch.toml
```
、“在itch上发布”、“上传到itch”。

不适用于： 在Steam上发布（请使用

steam-publish

）；游戏jam的范围规划（请使用

game-jam

——本技能仅涉及上传机制）；游戏本身的构建（请使用引擎相关技能）。

Core workflow

核心工作流程

Create the project page at
```
itch.io/game/new
```
. Set the Kind of project: keep Downloadable for native builds, or choose HTML for a browser-playable game (this is required for web builds — see Pitfalls). Set pricing/visibility (Draft until ready).
Install butler and log in. Download from
```
itchio.itch.io/butler
```
, add it to
```
PATH
```
, then
```
butler login
```
(opens a browser to authorize). Verify with
```
butler version
```
. For CI, use
```
BUTLER_API_KEY
```
instead — see the reference.
Prepare a portable build folder — the exact files a player runs, nothing extra. Push a folder (or a single
```
.zip
```
of that folder), not an installer and not a pre-compressed archive of archives (hurts patching; see Pitfalls).
Push to a channel:
```
butler push <dir> <user>/<game>:<channel>
```
. The channel name determines the platform tag (see Patterns). The first push uploads everything; later pushes to the same channel upload only the diff.
Set platform/HTML tags on the Edit game page if a channel wasn't auto-tagged correctly, then Save. For browser games also flip the page to HTML and tag the channel playable in browser.
Version your builds (optional but recommended):
```
--userversion 1.2.0
```
or
```
--userversion-file build.txt
```
so you control the version string players and the update API see.
Update later by pushing to the same channel again. Use
```
butler status <user>/<game>
```
to see channels/builds and
```
butler push-preview
```
to see what a push would change before sending it.

创建项目页面：访问
```
itch.io/game/new
```
。设置项目类型：原生构建版本选择“可下载”，浏览器可玩游戏选择HTML（这是网页构建版本的必填项——请查看注意事项）。设置定价/可见性（准备好前设为草稿状态）。
安装并登录butler：从
```
itchio.itch.io/butler
```
下载，将其添加到
```
PATH
```
，然后执行
```
butler login
```
（会打开浏览器进行授权）。执行
```
butler version
```
验证安装。对于CI环境，请使用
```
BUTLER_API_KEY
```
替代——请查看参考文档。
准备可移植的构建文件夹：包含玩家运行游戏所需的所有文件，无多余内容。推送文件夹（或该文件夹的单个
```
.zip
```
压缩包），不要推送安装程序，也不要推送已压缩的归档文件的归档包（会影响补丁更新；请查看注意事项）。
推送到渠道：
```
butler push <dir> <user>/<game>:<channel>
```
。渠道名称决定平台标签（请查看模式说明）。首次推送会上传所有内容；后续推送到同一渠道仅上传变更部分。
设置平台/HTML标签：如果渠道未自动正确添加标签，请在“编辑游戏”页面设置，然后保存。对于浏览器游戏，还需将页面类型切换为HTML，并为渠道添加“可在浏览器中游玩”标签。
为构建版本添加版本号（可选但推荐）：使用
```
--userversion 1.2.0
```
或
```
--userversion-file build.txt
```
，这样你可以控制玩家和更新API看到的版本字符串。
后续更新：再次推送到同一渠道即可。使用
```
butler status <user>/<game>
```
查看渠道/构建版本信息，使用
```
butler push-preview
```
查看推送会产生的变更，再执行推送。

Patterns

模式说明

1. The one command you need —

butler push

1. 必备命令——

butler push

bash

undefined

bash

undefined

butler push <directory-or-zip> <user>/<game>:<channel>

butler push <目录或压缩包> <用户名>/<游戏名>:<渠道名>

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)

undefined

undefined

2. Channel naming controls the platform tag (kebab-case, lowercase)

2. 渠道名称控制平台标签（短横线分隔，小写）

text

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).

text

渠道名称中的子串 -> 自动应用的标签：
  win / windows  -> Windows        linux -> Linux
  mac / osx      -> macOS          android -> Android
单个渠道可包含多个平台：例如Java jar包：
  butler push ./jar leafy/my-game:win-linux-mac
惯例：小写单词用短横线分隔（windows-beta, osx-demo, soundtrack）。
标签仅为初始推测——可随时在“编辑游戏”页面修改（然后保存）。

3. Version, verify, and preview

3. 版本验证与预览

bash

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

bash

butler version                              # 打印版本；确认安装及PATH配置
butler login                                # 授权当前机器（打开浏览器）

Set an explicit version string instead of itch's auto-incrementing integer:

设置明确的版本字符串，替代itch.io自动递增的整数：

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

undefined

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 # 列出渠道及最新构建版本/版本号 butler push-preview ./build leafy/my-game:windows # 显示新增/修改/删除/无变化内容，不会上传

undefined

4. First-time, hidden, and filtered pushes

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

bash

undefined

bash

undefined

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):

无需复制文件夹即可排除部分文件（--ignore可重复使用）：

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

undefined

butler push ./build leafy/my-game:windows --dry-run

undefined

Pitfalls

注意事项

Pushing an installer. itch.io patches portable builds; an installer (
```
.exe
```
/
```
.msi
```
) defeats patching and the itch app's auto-update, and may need admin rights players don't have. Push the extracted, runnable folder instead.
Pre-compressed builds. Pushing a heavily compressed archive (or an archive of archives) makes patches huge — a tiny change rewrites the whole compressed blob. Push uncompressed files; itch.io compresses on its side.
A folder containing only one
.zip
. butler auto-unzips it and pushes the contents (to avoid a "zip in a zip"). Pass
```
--no-auto-unzip
```
only if you truly want the zip uploaded as one opaque file.
HTML5 game shows as a download. Two switches are required: set the page Kind to HTML and tag the channel playable in browser on the Edit game page after the first push — neither happens automatically from the channel name.
--hidden
on an existing channel errors. It only applies when the push creates a new channel. Unhide later from Edit game.
Channel typos make duplicate slots.
```
windows
```
and
```
win-final
```
are different channels and create separate downloads. Decide your channel names up front and reuse them.
30 GB cap. itch.io rejects builds whose total uncompressed size exceeds 30 GB.
Secrets in CI logs. A
```
BUTLER_API_KEY
```
printed in a public log is compromised — revoke it immediately on the API keys page. See the reference for safe CI usage.

推送安装程序：itch.io针对可移植构建版本提供补丁更新；安装程序（
```
.exe
```
/
```
.msi
```
）会破坏补丁更新和itch应用的自动更新功能，且可能需要玩家没有的管理员权限。请推送解压后可直接运行的文件夹。
预压缩构建版本：推送高度压缩的归档文件（或归档文件的归档包）会导致补丁体积过大——微小的变更会重写整个压缩块。请推送未压缩的文件；itch.io会在服务器端进行压缩。
仅包含一个
.zip
的文件夹：butler会自动解压该文件并推送其内容（避免“压缩包嵌套”）。仅当你确实希望将zip作为单个不透明文件上传时，才使用
```
--no-auto-unzip
```
参数。
HTML5游戏显示为下载项：需要进行两项设置：将页面类型设为“HTML”，并在首次推送后于“编辑游戏”页面为渠道添加“可在浏览器中游玩”标签——这两项都不会通过渠道名称自动完成。
在已有渠道上使用
--hidden
会报错：该参数仅适用于推送创建新渠道的场景。后续可在“编辑游戏”页面取消隐藏。
渠道名称拼写错误会导致重复条目：
```
windows
```
和
```
win-final
```
是不同的渠道，会创建单独的下载项。请提前确定渠道名称并重复使用。
30GB容量限制：itch.io会拒绝未压缩总大小超过30GB的构建版本。
CI日志中的密钥泄露：如果
```
BUTLER_API_KEY
```
出现在公开日志中，会被泄露——请立即在API密钥页面撤销该密钥。请查看参考文档了解CI环境中的安全使用方法。

References

参考资料

For CI/CD (GitHub Actions/GitLab) with
```
BUTLER_API_KEY
```
, automated install via
```
broth
```
, the full flag list, and the update-check API, read
```
references/butler-ci.md
```
.
Primary docs: the butler manual —
```
itch.io/docs/butler
```
(installing, login, pushing).

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

itch-publish

Original

Translation

itch.io Publish (butler)

itch.io 发布（butler）

When to use

使用场景

Core workflow

核心工作流程

Patterns

模式说明

1. The one command you need —
`butler push`

1. 必备命令——
`butler push`

butler push <directory-or-zip> <user>/<game>:<channel>

butler push <目录或压缩包> <用户名>/<游戏名>:<渠道名>

2. Channel naming controls the platform tag (kebab-case, lowercase)

2. 渠道名称控制平台标签（短横线分隔，小写）

3. Version, verify, and preview

3. 版本验证与预览

Set an explicit version string instead of itch's auto-incrementing integer:

设置明确的版本字符串，替代itch.io自动递增的整数：

4. First-time, hidden, and filtered pushes

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

Hide a brand-new channel from the page until you're ready (NEW channels only):

新建渠道在准备好前隐藏（仅适用于新建渠道）：

Exclude files from the upload without copying the folder (--ignore is repeatable):

无需复制文件夹即可排除部分文件（--ignore可重复使用）：

Preview exactly what would be sent, without sending it:

预览将发送的内容，实际不发送：

Pitfalls

注意事项

References

参考资料

Related skills

相关技能

itch-publish

Original

Translation

itch.io Publish (butler)

itch.io 发布（butler）

When to use

使用场景

Core workflow

核心工作流程

Patterns

模式说明

1. The one command you need — butler push

1. 必备命令——butler push

butler push <directory-or-zip> <user>/<game>:<channel>

butler push <目录或压缩包> <用户名>/<游戏名>:<渠道名>

2. Channel naming controls the platform tag (kebab-case, lowercase)

2. 渠道名称控制平台标签（短横线分隔，小写）

3. Version, verify, and preview

3. 版本验证与预览

Set an explicit version string instead of itch's auto-incrementing integer:

设置明确的版本字符串，替代itch.io自动递增的整数：

4. First-time, hidden, and filtered pushes

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

Hide a brand-new channel from the page until you're ready (NEW channels only):

新建渠道在准备好前隐藏（仅适用于新建渠道）：

Exclude files from the upload without copying the folder (--ignore is repeatable):

无需复制文件夹即可排除部分文件（--ignore可重复使用）：

Preview exactly what would be sent, without sending it:

预览将发送的内容，实际不发送：

Pitfalls

注意事项

References

参考资料

Related skills

相关技能

1. The one command you need —
`butler push`

1. 必备命令——
`butler push`