Steam 构建流水线实战：2021 年 3 月个人游戏从本地打包到 SteamPipe 上传

构建流水线的目标

个人游戏不一定需要 CI 服务器，但一定需要可重复的构建流程。所谓可重复，是指你今天打出的 Steam 包，明天在同一提交上还能打出内容一致的包；你知道它来自哪个分支、哪个配置、哪些资源；上传到 Steam 后，能在客户端里验证。

很多上架前的问题来自手工打包：忘记切换正式场景，Debug 菜单还开着，Demo 包含正式版章节，上传了旧目录，Depot 缺少动态库。SteamPipe 本身不会替你判断游戏内容是否正确，它只负责把文件分发到玩家机器。开发者要负责“传上去的就是想发布的”。

构建目录设计

先把本地构建输出固定下来：

builds/
  windows_full/
  windows_demo/
  mac_full/
  linux_full/
steam/
  scripts/
  depots/
  logs/
docs/
  build-log.md

引擎导出到 builds/，SteamPipe 脚本从这些目录读取。不要让上传脚本直接读编辑器临时目录，也不要把多个平台混在一起。每次构建前清空目标目录，避免旧文件残留。

Depot 划分

小体量游戏可以只有一个 Windows Depot，但只要涉及 Demo、多个平台、原声带或 DLC，就要提前设计 Depot。常见划分：

Demo 和正式版是否共用 Depot，要谨慎。通常 Demo 是独立 App 或独立 Depot，内容边界更清楚。不要为了省事把正式版目录用脚本排除一部分来生成 Demo，除非排除规则非常稳定并经过测试。

脚本模板要提交，凭据不要提交

SteamPipe 上传通常使用 VDF 配置。建议提交模板，不提交本地凭据。模板里保留 App ID、Depot ID、构建描述和路径占位：

"appbuild"
{
  "appid" "你的 App ID"
  "desc" "windows demo build"
  "buildoutput" "../logs/"
  "contentroot" "../../builds/windows_demo/"
  "setlive" ""
  "depots"
  {
    "Depot ID" "depot_windows_demo.vdf"
  }
}

本地账号、密码、Steam Guard 处理不要写进仓库。脚本可以读取环境变量或提示输入。个人项目也要保护账号，因为 Steamworks 权限一旦泄露，影响的不只是一个构建。

构建编号规则

每个构建都要有编号。编号不需要复杂，但要包含日期、目标和序号：

2021.03.16-full-win-01
2021.03.16-demo-win-02
2021.03.17-rc1-win-01

构建编号要出现在三个地方：游戏主菜单或日志、构建记录、SteamPipe 描述。这样玩家截图、日志或审核反馈回来时，你能知道它对应哪一包。

上传前本地检查

上传前先做本地构建检查，不要把 Steam 当测试工具：

这一步非常朴素，但能挡住大多数低级错误。尤其是 Debug 菜单和测试快捷键，个人开发者经常忘记关闭。

Steam 客户端验证

上传到 Steam 后，要通过 Steam 客户端安装，而不是继续运行本地目录。验证重点：

• 安装路径是否干净，没有本地构建残留。
• Steam 启动项是否正确。
• 覆盖层能否打开。
• 成就、云存档、语言、控制器是否按预期工作。
• 卸载后是否留下异常文件。
• 更新一个新构建后，旧存档是否仍可加载。

测试时可以准备一个“干净用户”环境。不要总用开发账号和开发机器测，因为本地可能已经有配置、存档、插件或运行库，掩盖了新玩家会遇到的问题。

分支管理

Steam 分支建议至少分为：

不要把刚上传的包直接设为 default。先放 internal 或 review 分支，完成安装和烟测后再考虑切换。上线前尤其要注意分支密码和可见性，不要让未公开版本被错误访问。

增量更新和文件清理

SteamPipe 支持增量分发，但这不意味着你可以让构建目录长期堆积无用文件。删除旧资源、重命名目录、替换大文件时，要检查玩家端是否能正确更新。尤其是自研资源包，如果每次都打成一个巨大压缩包，小改动也会导致玩家下载很大补丁。

资源包设计时要考虑更新颗粒度：

个人游戏不一定要做复杂分包，但至少不要把日志、临时文件、编辑器缓存打进包里。

常见返工问题

Steam 构建审核或自测中常见问题包括：

每次返工都要更新构建日志，不要只在聊天工具里说“修了”。后面再遇到同类问题时，记录能直接复用。

发布当天流程

发布当天不要第一次运行完整流程。至少提前一周演练一次：

1. 从发布分支拉取干净代码。
2. 清空构建目录。
3. 导出正式包。
4. 写入构建编号。
5. 本地运行烟测。
6. SteamPipe 上传到 internal。
7. Steam 客户端安装测试。
8. 切到 review 或候选分支。
9. 记录结果和已知问题。

真正上线当天，只做已经演练过的动作。不要临时改脚本、改目录、改 App ID。个人开发者时间紧，更要减少当天的不确定性。

最终检查清单

• 构建输出目录固定且每次清理。
• Depot 划分和 Demo 边界清楚。
• VDF 模板提交，凭据不进仓库。
• 构建编号贯穿游戏、日志和 SteamPipe 描述。
• 上传前完成本地烟测。
• 上传后通过 Steam 客户端验证。
• 分支切换有记录，不直接把新包推 default。
• 返工问题写入构建日志。

SteamPipe 的难点不在命令本身，而在流程一致。只要每个包都能追溯、验证和回滚，个人开发者也能把发布风险控制在可接受范围内。

失败上传也要记录

上传失败不要只重试。SteamPipe 失败可能来自登录、权限、路径、文件锁定、磁盘空间、Depot 配置或网络问题。每次失败都要记录错误摘要和处理方式，尤其是权限类和路径类问题。因为同一个问题很可能在正式发布当天再次出现。

建议在 steam/logs/ 旁边保留一份人工记录：失败时间、使用脚本、目标分支、错误信息、是否影响线上分支。这样团队只有一个人，也能在压力较大的发布窗口保持判断力。构建流程越机械，越要把异常写下来。