steam-publish

Steam 发布（Steamworks + SteamPipe）

将已完成的构建发布到 Steam 商店页面。两个流程并行推进，发布前都必须获批：商店页面（展示信息）和构建（SteamPipe 上传 + 发布检查清单）。本技能是操作检查清单；深入的构建脚本、CI/CD 和故障排查详情请参阅 references/steampipe-build-scripts.md。

适用场景

• 用于设置 Steam 应用、创建或编辑商店页面、配置 depot 和 package、通过 SteamPipe/steamcmd 上传构建、管理 Beta 分支，或发布和更新 Steam 游戏。
• 触发条件：steam_appid.txt、Steamworks SDK tools/ContentBuilder、app_build_*.vdf、steamcmd、“在 Steam 上发布”、“depot”、“将构建设为上线”。

不适用场景：在 itch.io 上发布（请使用 itch-publish）；在游戏中编写 Steamworks API（成就、云存档和覆盖层由引擎 SDK 集成实现，不属于此处内容）；商店或财务建议（定价策略、税务）——请引导用户查阅 Steamworks 文档并咨询自己的顾问。

前提条件（按顺序完成一次即可）

1. 合作伙伴帐户 + Steam Direct 费用。 每个新应用都需要缴纳 Steam Direct 可退还费用（撰写本文时每个应用为 USD $100）。你会获得一个App ID——可在 Steamworks 主页上找到。请将 App ID 视为以下所有事项的关键。对于最初的几款游戏，Valve 还会要求从支付应用费用到发布游戏之间至少间隔 21 天，因此请在计划发布日期前尽早缴费。
2. 专用构建帐户，并遵循最小权限原则。 构建需要使用合作伙伴组中的 Steam 帐户，并拥有编辑应用元数据和向 Steam 发布应用更改权限。请创建一个仅具备这些权限的独立构建帐户（不要使用管理员登录帐户）。发布应用还需要管理定价和折扣权限。
3. 在上传机器上下载 Steamworks SDK。 SteamPipe 工具位于 tools/ContentBuilder/ 下。

安全提示：切勿将帐户密码或 config.vdf 登录令牌提交到代码仓库。 关于受支持的令牌工作流，请参阅参考文档中的 CI/CD 部分。

核心工作流程

1. 配置应用（App Admin）。
   • 在 Installation 下设置启动选项（按操作系统指定可执行文件路径和参数）。对于位于子文件夹中的 exe，将子文件夹填入 Executable 字段——不要添加前导斜杠或点。
   • 在 Depots 页面添加Depot（Depot 是文件存储桶）。为每个 Depot 命名（“基础内容”“Windows 内容”）。除非 Depot 确实特定于操作系统或语言，否则保留 [所有语言] / [所有操作系统]。
   • **授予自己对 Depot 的访问权限：**在 Associated Packages & DLC 页面将其添加到你的 Developer Comp 包中，否则你将无法拥有自己上传的内容。
   • 发布配置。配置未发布是导致上传失败的最常见原因。
2. **构建商店页面（商店展示流程）。**填写图形素材、描述、标签、预告片和系统要求。完成后，点击 标记为准备审核。商店审核约需 3–5 个工作日；请至少提前 7 个工作日提交。发布前必须在 即将推出 状态保持至少 2 周。
3. **创建构建脚本。**从下方 Patterns 中的简单应用构建 .vdf 开始；对于多 Depot／多平台应用，请使用 Depot 脚本（参见参考文档）。脚本会将本地文件映射到 Depot，并指定构建输出和日志的存放位置。
4. **检查脚本，然后初始化 steamcmd 并上传。**上传前运行 python scripts/check_steam_build.py <app_build.vdf>（Pattern 3），并修复所有错误；然后运行一次 steamcmd 以自行更新，再运行构建（Patterns）。 steamcmd 会将文件分块（约 1 MB），仅上传有更改的分块，并注册一个全局 BuildID。
5. **将构建设为某个分支的当前版本。**前往 https://partner.steamgames.com/apps/builds/<AppID>， 选择构建，点击 预览更改，然后点击 立即设为分支当前版本。先在 beta 分支上测试（分支设置请参阅 references/steampipe-build-scripts.md）。
6. 完成 Game Build 检查清单并标记为准备审核（商店展示内容必须先于构建审核提交）。两个流程都必须通过审核。
7. 手动发布。审核通过且“即将推出”状态已满足时长后，点击绿色的 Release App 按钮 → Publish Now → Release Now。已通过审核的作品不会自动发布。
8. 稍后更新时，上传新构建并将其设为 default 分支的当前版本（手动），或先发布到 beta 分支。参见 references/steampipe-build-scripts.md。

模式

1. SteamPipe ContentBuilder 布局（Steamworks SDK）

tools/ContentBuilder/
  builder/         steamcmd.exe (Windows)   <- run once to bootstrap
  builder_linux/   steamcmd (Linux)
  builder_osx/     steamcmd (macOS)
  content/         <- your final, runnable build goes here (the files players get)
  output/          build logs + chunk cache (safe to delete; speeds up re-uploads)
  scripts/         <- your *.vdf build scripts live here

2. 最简应用构建脚本 — app_build_1000.vdf

// AppID 1000 with one depot (1001): upload everything under ../content recursively.
// VDF is Valve KeyValues: "key" "value", braces for nesting. Adjust IDs to your app.
"AppBuild"
{
    "AppID"       "1000"                 // your App ID
    "Desc"        "1.0.0 launch build"   // internal only; visible in Your Builds

    "ContentRoot" "..\content\"          // root of files to upload (relative to this file)
    "BuildOutput" "..\output\"           // logs + chunk cache

    "Depots"
    {
        "1001"                           // your Depot ID
        {
            "FileMapping"
            {
                "LocalPath"  "*"         // all files from ContentRoot
                "DepotPath"  "."         // mapped to the depot root
                "recursive"  "1"         // include subfolders
            }
        }
    }
}

3. 上传前检查构建脚本（只读，无需登录）

# Run before you upload. Parses the app script and every depot script, resolves
# ContentRoot/LocalPath exactly as SteamPipe documents, and counts what each depot would upload.
python scripts/check_steam_build.py tools/ContentBuilder/scripts/app_build_1000.vdf
python scripts/check_steam_build.py app_build_1000.vdf --json --strict   # CI gate

ERROR depot_build_1002.vdf:7: LocalPath "bin\*" matches no files under ../content
  fix: LocalPath is relative to the content root; check the folder names, ...
Depots:
  1001 [depot_build_1001.vdf]: 412 files, 1.8 GiB, 3 excluded, from ../content
Summary: 1 errors, 0 warnings in 3 files checked

退出码 0 = 无错误，1 = 存在错误（或使用 --strict 时存在警告），2 = 文件缺失或不是 AppBuild 脚本。错误包括：VDF 无法解析、AppID 或 DepotID 缺失／不是数字、没有 Depot、Depot 重复、Depot 脚本缺失、ContentRoot 或 InstallScript 缺失、LocalPath 未匹配到任何内容或指向一个普通文件夹，以及 Depot 将上传零个文件。警告包括：设置了 SetLive 却没有 Preview（会立即在该分支上线；对于 default 会发出更醒目的警告）、缺少 Desc、Local 构建、BuildOutput 位于 ContentRoot 内，以及键拼写错误。上传前请查看每个 Depot 的文件数量和大小。 请使用相对于此技能目录的脚本路径，或先解析已安装的技能路径。该脚本需要 Python 3.10+，无需其他依赖，并且绝不会登录或上传。

4. 上传构建（Windows；其他平台请替换为对应的平台构建工具）

REM Run from the SDK. Bootstrap once, then build. Use a build account, not your admin login.
tools\ContentBuilder\builder\steamcmd.exe ^
  +login <build_account> <password> ^
  +run_app_build ..\scripts\app_build_1000.vdf ^
  +quit

What happens: steamcmd self-updates -> logs in -> for each depot, hashes files into ~1 MB
chunks -> uploads only NEW chunks -> writes a depot manifest -> finishes with a global
BuildID. The build is NOT live yet; set it live per the workflow above.

5. 使用预览构建安全迭代（不上传任何内容）

// Add to the AppBuild block to validate file mappings without uploading:
"Preview" "1"     // outputs logs + a file manifest into BuildOutput only
// And to auto-set live on a BETA branch after a successful build (never 'default'):
"SetLive" "beta-qa"

注意事项

• 无法自动将 default 分支设为上线状态。 SetLive 仅适用于 beta 分支；你必须在 App Admin 中手动将默认（面向客户的）构建设为上线状态。请据此规划发布。
• 必须先通过商店页面审核，才能提交构建。 在提交商店页面内容之前，无法提交构建以供审核；两者都必须通过审核，而且「即将推出」页面必须运行约 2 周。
• 游戏不会自动发布。 即使审核通过，也必须由人工在选定时间点击 Release App。
• Mac/Linux 不会安装任何内容。 几乎总是因为软件包中没有包含特定于操作系统的 depot。请在 Associated Packages & DLC 中将每个 depot 都添加到软件包。
• 应用配置尚未发布。 “Failed to get application info” / 构建错误通常意味着 depots、启动选项或 App ID 配置尚未 Published。
• 构建时出现 status = 6。 构建账号没有 App ID 的权限，或者 ContentRoot/LocalPath 指向了错误的（空）路径。
• 提交登录令牌。 config.vdf 中的 Steam Guard 令牌和账号密码都属于机密信息。请勿将它们放入仓库；请使用参考文档中的 CI 工作流。
• 已发布应用的安全等待期。 更改构建账号的邮箱/手机号后，必须等待 3 天，才能将 released 应用的构建设为上线状态——请勿在发布前临时重新配置账号。

参考资料

• 有关高级多 depot/多平台构建脚本、FileExclusion/FileProperties、beta 分支设置、CI/CD 登录令牌工作流以及 SteamPipe 故障排查表，请阅读 references/steampipe-build-scripts.md。
• scripts/check_steam_build.py — 以只读方式检查应用构建脚本、depot 脚本和内容文件夹；--help 会列出所有检查项和退出代码。
• 主要文档：Steamworks 的“上传到 Steam”（partner.steamgames.com/doc/sdk/uploading）、“发布流程”（/doc/store/releasing）、“分支（Betas）”（/doc/store/application/branches）、“Depots”（/doc/store/application/depots）、“入门指南”（/doc/gettingstarted/onboarding，首个游戏的等待期）和“审核流程”（/doc/store/review_process）。

相关技能

• itch-publish — 使用 butler 在 itch.io 上发布同一款游戏（通常与 Steam 发布同时进行）。
• game-jam / prototype-fast — 同一项目生命周期的早期阶段。