如何用 GitHub Actions 实现 Steam 自动化发布本文分享了 HagiCode Desktop 项目中实现 Steam 自动化发布的完整方案从 GitHub Release 到 Steam 平台的全链路自动化流程包括 Steam Guard 认证、多平台 Depot 上传等关键技术细节。背景Steam 平台的发布流程其实和传统的应用分发方式挺不一样的。Steam 有自己的一套完整更新分发系统开发者得通过 SteamCMD 工具把构建产物上传到 Steam 的 CDN 网络而不是像其他平台那样直接丢个下载链接就完事了。HagiCode Desktop 项目计划上架 Steam 平台这也算是给我们的发布流程带来了点新挑战需要把现有的构建产物转换成 Steam 兼容的格式得通过 SteamCMD 工具上传到 Steam 平台还必须处理 Steam Guard 认证这玩意儿需要支持多平台Linux、Windows、macOS的 Depot 上传还要实现从 GitHub Release 到 Steam 的自动化流转项目此前已经实现了便携版模式portable version mode允许应用检测打包在 extra 目录中的固定服务载荷。我们的目标其实就是让这套便携版模式和 Steam 分发能无缝集成罢了。关于 HagiCode本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode 是一个 AI 代码助手项目支持桌面端运行我们正在推进 Steam 平台的上架工作因此才需要建立一套可靠的自动化发布流程。架构设计整个 Steam 发布流程的核心是一个 GitHub Actions 工作流它把整个过程分为三个主要阶段┌─────────────────────────────────────────────────────────────┐ │ GitHub Actions Workflow (Steam Release) │ ├─────────────────────────────────────────────────────────────┤ │ 1. 准备阶段: │ │ - 检出 portable-version 代码 │ │ - 从 GitHub Release 下载构建产物 │ │ - 解压并准备 Steam 内容目录 │ │ │ │ 2. SteamCMD 设置: │ │ - 安装/复用 SteamCMD │ │ - 使用 Steam Guard 进行认证 │ │ │ │ 3. 发布阶段: │ │ - 生成 Depot VDF 配置文件 │ │ - 生成 App Build VDF 配置文件 │ │ - 调用 SteamCMD 上传到 Steam │ └─────────────────────────────────────────────────────────────┘这种设计的优势怎么说呢复用现有的 GitHub Release 产物避免重复构建毕竟谁愿意重复劳动呢通过自托管运行器实现安全隔离多一层保障总是好的支持预览模式和正式发布分支切换灵活一点完整的错误处理和日志记录出问题的时候不至于太迷茫工作流实现触发参数设计我们的工作流支持以下关键参数inputs:release:# Portable Version 发布标签description:要发布的版本标签如 v1.0.0required:truesteam_preview:# 是否生成预览构建description:是否为预览模式required:falsedefault:falsesteam_branch:# 设置为 live 的 Steam 分支description:目标 Steam 分支required:falsedefault:previewsteam_description:# 构建描述覆盖description:构建描述required:false自托管运行器配置出于安全考虑我们使用带 steam 标签的自托管运行器runs-on:-self-hosted-Linux-X64-steam这样可以确保 Steam 发布在专用运行器上执行保持敏感凭据的安全隔离。毕竟安全这事儿多注意一点总是好的。并发控制为了避免同一版本的发布相互干扰我们配置了并发控制concurrency:group:portable-version-steam-${{github.event.inputs.release}}cancel-in-progress:false注意这里设置cancel-in-progress: false因为 Steam 发布过程可能较长我们也不想因为新的触发就取消正在进行的发布。毕竟发布个版本也不容易总得让人家跑完不是核心脚本实现准备发布输入prepare-steam-release-input.mjs脚本负责准备发布所需的输入// 下载 GitHub Release 的构建清单和产物清单constbuildManifestawaitdownloadBuildManifest(releaseTag);constartifactInventoryawaitdownloadArtifactInventory(releaseTag);// 下载各平台的压缩包for(constplatformof[linux-x64,win-x64,osx-universal]){constartifactUrlgetArtifactUrl(artifactInventory,platform);awaitdownloadArtifact(artifactUrl,platform);}// 解压到 Steam 内容目录结构awaitextractToSteamContent(sources,contentRoot);Steam Guard 认证Steam 要求使用 Steam Guard 保护账户我们实现了基于共享密钥的代码生成算法functiongenerateSteamGuardCode(sharedSecret,timestampDate.now()){constsecretdecodeSharedSecret(sharedSecret);consttimeMath.floor(timestamp/1000/30);consttimeBufferBuffer.alloc(8);timeBuffer.writeBigUInt64BE(BigInt(time));// 使用 HMAC-SHA1 生成时间基础的一次性代码consthashcrypto.createHmac(sha1,secret).update(timeBuffer).digest();// 转换为 5 字符的 Steam Guard 代码constcodesteamGuardCode(hash);returncode;}这个实现基于 Steam Guard 的 TOTPTime-based One-Time Password机制每 30 秒生成一个新的验证码。毕竟安全这东西还是得用靠谱的方式才行。VDF 配置生成VDFValve Data Format是 Steam 使用的配置格式我们需要生成两种类型的 VDF 文件Depot VDF用于配置各个平台的内容functionbuildDepotVdf(depotId,contentRoot){return[DepotBuildConfig,{,DepotID ${escapeVdf(depotId)},ContentRoot ${escapeVdf(contentRoot)}, FileMapping, {, LocalPath *, DepotPath ., recursive 1, },}].join(\n);}App Build VDF用于配置整个应用构建functionbuildAppBuildVdf(appId,depotBuilds,description,setLive){constvdf[appbuild,{,appid ${appId},desc ${escapeVdf(description)},contentroot ${escapeVdf(contentRoot)}, buildoutput build_output, depots, {];for(const[depotId,depotVdfPath]ofObject.entries(depotBuilds)){vdf.push(${depotId} ${depotVdfPath});}if(setLive){vdf.push(});vdf.push(setlive ${setLive});}vdf.push(});returnvdf.join(\n);}SteamCMD 调用最后通过调用 SteamCMD 执行上传awaitrunCommand(steamcmdPath,[login,steamUsername,steamPassword,steamGuardCode,run_app_build,appBuildPath,quit]);这一步算是整个流程的最后一跃跨过去就完成了…多平台 Depot 处理Steam 使用 Depot 系统管理不同平台的内容我们支持三种主要的 Depot平台Depot 标识架构支持Linuxlinux-x64x64_64Windowswin-x64x64_64macOSosx-universaluniversal, x64_64, arm64每个 Depot 都有独立的内容目录和 VDF 配置文件这样可以确保不同平台的用户只下载自己需要的内容。毕竟流量也是钱能省一点是一点。发布流程步骤 1准备 GitHub Release首先需要在 portable-version 仓库创建一个 GitHub Release包含各平台的压缩包构建清单{tag}.build-manifest.json产物清单{tag}.artifact-inventory.json步骤 2触发 Steam 发布工作流通过 GitHub Actions 手动触发工作流填写必要参数release: 要发布的版本标签如 v1.0.0steam_branch: 目标分支如preview或publicsteam_preview: 是否预览模式步骤 3自动执行发布流程工作流会自动执行以下步骤下载并解压 GitHub Release 产物安装/更新 SteamCMD生成 Steam VDF 配置文件使用 Steam Guard 认证上传内容到 Steam CDN设置指定分支为 live这一套流程走下来也算是把该做的都做了。配置指南必需的 Secrets 配置在 GitHub 仓库设置中配置以下密钥Secret 名称说明STEAM_USERNAMESteam 账户用户名STEAM_PASSWORDSteam 账户密码STEAM_SHARED_SECRETSteam Guard 共享密钥可选STEAM_GUARD_CODESteam Guard 代码可选STEAM_APP_IDSteam 应用 IDSTEAM_DEPOT_ID_LINUXLinux Depot IDSTEAM_DEPOT_ID_WINDOWSWindows Depot IDSTEAM_DEPOT_ID_MACOSmacOS Depot ID这些配置项其实也没什么特别的就是该有的都得有罢了。环境变量配置变量名称说明默认值PORTABLE_VERSION_STEAMCMD_ROOTSteamCMD 安装目录~/.local/share/portable-version/steamcmd最佳实践Steam Guard 认证管理首次运行需要手动输入 Steam Guard 代码之后建议配置共享密钥自动生成代码。这样可以避免每次发布都需要手动干预毕竟谁也不想每次都重复同样的操作。SteamCMD 会保存登录令牌后续可以复用。但要注意令牌的有效期过期后还是得重新认证的这也没办法。内容目录结构确保 Steam 内容目录结构正确steam-content/ ├── linux-x64/ # Linux 平台内容 ├── win-x64/ # Windows 平台内容 └── osx-universal/ # macOS 通用二进制内容每个目录下应该包含对应平台的完整应用文件。这点倒也没什么好说的该怎么做就怎么做。预览模式使用预览模式不会设置任何分支为 live适合测试验证if[$STEAM_PREVIEW_INPUT true]; then cmd(--preview) fi这样可以先上传到 Steam 平台进行验证确认无误后再切换到正式分支。多一层验证总是好的。错误处理和日志脚本包含了完善的错误处理和日志记录验证 GitHub Release 存在性检查必需的元数据文件确保平台内容存在生成 GitHub Actions 摘要报告这些信息对于调试和审计都非常有价值毕竟出问题的时候能有个线索总比一头雾水要好。产物管理工作流生成两种产物portable-steam-release-preparation-{tag}: 发布准备元数据portable-steam-build-metadata-{tag}: Steam 构建元数据这些产物可以用于后续的审计和调试保存时间建议设置为 30 天。反正也不占多少地方留着也无妨。实际应用在 HagiCode 项目中这套自动化发布流程已经成功运行了多个版本。从 GitHub Release 到 Steam 平台的整个链路完全自动化无需人工干预。这大大提高了我们的发布效率和可靠性。之前手动发布一个版本需要 30 分钟以上的时间现在只需要几分钟就能完成整个流程。时间这东西省下来总归是好的。更重要的是自动化流程减少了人为错误的可能性每次发布都是标准化的流程结果也更加可预测。毕竟重复的事情交给机器去做人也轻松点。总结通过本文分享的方案我们实现了从 GitHub Release 到 Steam 平台的完全自动化支持多平台的 Depot 上传基于 Steam Guard 的安全认证预览模式和正式发布的灵活切换完善的错误处理和日志记录这套方案不仅适用于 HagiCode 项目也可以为其他计划上架 Steam 平台的项目提供参考。如果你也在考虑 Steam 自动化发布希望本文的实践能够对你有所帮助。其实技术这东西说复杂也复杂说简单也简单。关键是找到适合自己的方式罢了。如果本文对你有帮助欢迎来 HagiCode 的 GitHub 仓库给个 Star或者访问官网了解更多信息。参考资料SteamCMD DocumentationSteamworks SDKHagiCode 项目地址HagiCode 官网HagiCode 安装指南HagiCode Desktop 桌面端原文与版权说明感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。本内容采用人工智能辅助协作,最终内容由作者审核并确认。本文作者: newbe36524原文链接: https://docs.hagicode.com/go?platformcsdntarget%2Fblog%2F2026-04-16-steam-release-automation-github-actions%2F版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!