Ludo Atlas · 管线 · 构建与发布管线¶
管线与工作流。定位：把「代码冻结」到「渠道收包」之间的工程侧事务做成一条可复现、可追溯、可回滚的通道，版本对得上、渠道分得清、出问题退得回。 配套：《技术实现手册》·《制作管理手册》·《全平台上架手册》·《避坑大全》。 与《全平台上架手册》的分工：《全平台上架手册》 讲商店提审、资质与合规的流程；本页讲工程侧的构建、打包、签名、归档与回滚，范围到「包交到渠道手里」为止。本文不写具体命令，接口细节以各引擎与平台官方文档为准。
1. 定位与适用¶
构建与发布管线解决一个问题：同一条游戏内容，如何稳定地变成每个渠道都能直接使用的包。在这条管线里，「能跑」不够，四个条件缺一不可：
- 可复现：任意一个发过的版本，能由对应的代码与资产重新构建，行为一致。
- 可追溯：任意一个包，能回答它来自哪个提交、哪个构建号、谁在什么时候构建的。
- 可分渠道：商店包、测试包、内部分发包各走各的口径，互不污染。
- 可回滚：线上出事时，能在约定时限内退回上一个稳定版本。
什么时候需要立这套东西：只要有构建离开你的开发机（发给测试者、上测试渠道、提审商店），就需要。单人开发可以裁剪到最小（版本号加归档加一条命令出包），但「手拼一个包发给玩家」这种做法，从第一个外部测试者开始就不该再用。
四个概念先定下来，后文反复使用：
| 概念 | 含义 | 纪律 |
|---|---|---|
| 档位（flavor） | 同一份代码按用途分出的构建口味：开发、内部、测试、发布 | 差异写进配置，不靠人工记忆 |
| 构建号 | 每次构建自动生成的全局递增序号 | 只增不减、不复用、不手填 |
| 渠道包 | 为某个商店或分发渠道定制的产物，含平台与渠道标识 | 一个包只归属一个渠道 |
| 签名 | 平台验证「这个包确实出自你」的身份机制，配套证书与私钥 | 证书集中托管，私钥永不进代码库 |
边界说明：上架流程、资质与审核节奏在《全平台上架手册》，本页不重复；构建农场的搭建与流水线细节属于 CI/CD 管线（规划中），本页只定义它必须满足的规则；版本控制与资产方案是另一条管线的事，本页假设代码与资产已经能按提交重建。
2. 工具链¶
工具链按六个环节铺开，每个环节只留一个主力工具：
| 环节 | 工具类型 | 常见选择 | 选型注意 |
|---|---|---|---|
| 构建入口 | 引擎的命令行导出与无界面构建 | 引擎自带的无界面导出加项目内构建脚本 | 一切参数进脚本，人只填版本与档位 |
| 构建编排 | CI 服务加版本写入脚本 | 托管 CI 或自建构建机 | 干净环境、工具链版本锁定、构建号全局递增 |
| 打包 | 安装器与压缩工具 | 平台安装器生成器、归档格式工具 | 打包格式按渠道要求提前定 |
| 签名 | 平台签名工具 | 各平台官方签名链路 | 与密钥库接线，不落地明文私钥 |
| 归档 | 制品库或对象存储 | 内部制品库、对象存储加台账 | 只增不改，能按版本检索 |
| 分发 | 内部分发与测试渠道 | 内部分发页、平台测试轨道 | 访问受控，注出版本与有效期 |
选型三条纪律：
- 一条命令出包是底线，脚本与项目同库同审。需要人手点五个菜单才能出包的工具链，不可能自动化也不可能稳定；脚本散落在个人机器上等于没有，改动走代码评审。
- 构建环境与开发环境分离。构建机不装多余运行库、不留历史文件，保证「干净能过」；开发机流畅不作数（方法同《技术实现手册》）。
- 密钥与证书不进代码库。构建机从集中的密钥库取用，最小权限，取用留日志。
3. 流程与规范¶
3.1 构建目标矩阵：平台 × 档位 × 渠道¶
矩阵的第一维是档位，四档固定，用途不混：
| 档位 | 用途 | 配置取向 | 可交给谁 |
|---|---|---|---|
| 开发档 | 本机日常调试 | 调试全开、可连本地服务 | 开发者 |
| 内部档 | 团队与 QA 日常验证 | 带调试符号、留诊断入口 | 团队内部 |
| 测试档 | 外部测试者与平台测试渠道 | 接近发布配置，日志收紧 | 受控外部 |
| 发布档 | 正式商店与渠道 | 优化全开、无后门、符号另存 | 全部玩家 |
第二维是平台与渠道，工程侧要准备什么，因交付形态而异：
| 平台与渠道 | 交付形态 | 工程侧特有项 |
|---|---|---|
| PC 商店 | 安装器或压缩包、商店后台上传 | 多架构、增量上传、运行库打包 |
| 主机平台 | 认证候选包 | 平台工具链、专用签名与版本格式、认证检查项 |
| 移动商店 | 含签名的商店包 | 证书与描述文件、加固、分包、目标系统版本 |
| 国内安卓渠道 | 渠道包 | 渠道标识、渠道 SDK、多包管理 |
| 小游戏平台 | 平台包 | 分包与远程资源、平台工具链 |
| Web | 静态资源包 | 缓存策略、路径前缀、版本指纹 |
矩阵纪律：不在矩阵里的组合不允许存在。每个格子（平台加档位加渠道）的构建参数写在一份配置表里：优化开关、日志级别、服务器地址、渠道标识。有人要求「临时改一下再出个包」，改的是配置表再走构建，不允许在产物上手动打补丁。
3.2 版本号与产物命名¶
版本体系用双轨制：
- 对外版本号：三段式（主版本、次版本、修订号），用于商店与玩家沟通；只在里程碑跳变，发布后不可改写；同一渠道内必须单调递增，商店会拒收重用过的版本号。
- 构建号：全局递增的整数，每次构建自增，不复用、不回退；来源自动化（提交计数或流水线计数器），禁止手填。一个对外版本号通常对应多个构建号，台账记录最终上线的是哪一个。
规则清单：
- 版本号与构建号必须写进产物内部（可执行文件属性、应用清单、游戏内可见角标），不只存在于文件名；玩家报障截图里要带得出这两个数字。
- 产物命名包含定位五要素：项目、版本、构建号、平台与架构、档位与渠道；全小写、不用空格与中文、分隔符全库统一，保证可脚本解析与稳定排序（示例：
项目名-1.2.0-b514-win64-release-steam，字段顺序全库统一）。 - 提交号与构建号的对应关系进台账；打标签发布时，标签、构建号、台账三处必须一致，任一缺失，该次发布视为无效。
3.3 构建自动化：命令行导出与触发规则¶
自动化的地基是引擎的命令行导出（无界面构建）：没有它，一切免谈；有了它，才轮到编排。
- 手动触发也走同一入口：允许人工发起构建，但必须走同一套脚本与同一组参数（版本、档位、渠道），禁止「进编辑器手动导出」应急；应急一次，台账就断一次。
- CI 触发三类时机，各司其职：
| 时机 | 触发源 | 出什么包 | 服务谁 |
|---|---|---|---|
| 日常 | 每次合并到主干 | 冒烟构建（能启动、能进关卡） | 开发与 QA |
| 定时 | 每天固定时刻 | 内部档完整包 | 团队日常验证 |
| 里程碑 | 发布标签或人工批准 | 测试档与发布候选包 | 测试者与渠道 |
- 输入全自动：构建机只从版本库取料，不留任何手工改动，改完先提交再构建；版本号、档位、渠道以参数注入，构建过程零交互，任何需要人当场回答的步骤都是自动化缺口。
- 构建产物三件套：产物本体、构建日志、台账记录，一次构建生成一份，缺一不可。
3.4 渠道包管理：商店包、测试渠道、内部分发¶
一个版本可以出多个渠道包，但渠道差异只允许活在打包层：渠道标识、渠道 SDK、登录与支付、服务器地址、图标与名称。做法是每个渠道一份配置，打包时注入；禁止把渠道差异写成代码里的条件分支，那种分支每加一个渠道就要全量回归。
- 商店包：用于提审与正式上架的包，一旦上传，其版本号在该商店不可复用；所以顺序永远是「测试渠道先验，商店包后出」，反着做等于拿提审名额做试验。
- 测试渠道：用平台自带的测试轨道（移动的测试分组、PC 商店的测试分支等）；每次给测试者的包，附三行说明：哪个版本、哪天起可下载、问题往哪报。测试渠道上的包与将发布的商店包必须出自同一构建参数，只差渠道标识。
- 内部分发与归属：内部档放进受控的内部分发页或制品库，注出版本号、构建号与有效期，过期自动清理；每个渠道包都要能回答「来自哪个构建号、谁上传的、什么时候」，同一构建产物不允许改配置后二次分发。
3.5 签名与证书管理（概念与纪律）¶
签名是平台验证「这个包确实出自你」的机制，证书与私钥是身份资产。类型与失效后果先认清：
| 场景 | 凭证形态 | 丢失或过期的后果 |
|---|---|---|
| iOS | 发布证书与描述文件（有有效期） | 证书失效则无法再发版；描述文件过期需重签 |
| Android | 签名密钥（含上传密钥） | 密钥丢失且无重置方案，更新同一应用的路被堵死，等同换应用重来 |
| Windows 与 macOS | 代码签名证书、公证凭证 | 无法签发新包；已发版本不受影响，新版本发布冻结 |
| 主机平台 | 平台专用签名与凭证 | 认证包无法产出，直接停摆 |
| 小游戏平台 | 平台侧密钥与后台配置 | 无法上传与更新 |
管理纪律：
- 集中托管、双人经办：证书与私钥进统一的密钥库（密码管理工具或专用密钥库），禁止只存在于个人机器、邮件附件与聊天记录里；至少两人有取用权限并知道流程，人员变动时交接清单必须有「凭证与权限」一项。
- 离线与异地备份：私钥离线备份至少两份，其中一份异地；备份本身加密。
- 登记在册：每份凭证记录用途、负责人、有效期与续期方式；到期前提前续，商店证书到期等于发版冻结。
- 最小权限与留痕：构建机按需取用，取用与签名操作留日志；私钥永远不进代码库、不进构建日志。
- 定期演练：至少做一次「换台机器、用备份凭证、重建签名包」的演练；没演练过的备份不算备份。
3.6 产物归档与回滚¶
归档的对象不是「所有构建」，而是每一个对外发过的构建：所有测试渠道与商店版本、所有内部分发过的包。归档四件套：
| 归档项 | 用途 | 保留策略 |
|---|---|---|
| 产物本体 | 回滚与取证 | 商店在售版本与主机认证版本永久 |
| 调试符号文件 | 解析线上崩溃堆栈 | 与对应版本同寿命 |
| 构建日志 | 复现与追责 | 至少保留到该版本退出支持 |
| 台账记录 | 版本历史与对应关系 | 永久 |
回滚的三个前提，缺一个就回不去：归档完整（旧包与旧符号都拿得出来）；可重复构建（万不得已重建旧版本时，能由旧标签重建出行为一致的包）；流程演练过（负责人、时限与操作路径提前定好，别等事故当晚现学）。
回滚的现实口径：多数商店不支持「降版本」；工程上的通用路径是把上一个稳定版本重新构建成更高版本号推送（或推回滚补丁），主机的认证节奏会让这条路更慢。所以「回滚时间」是一个要写进预案并演练过的数字，不是一句口号。
4. 自动化与验收¶
机器管形式，人管判断。下列检查全部脚本化，接在构建与分发之间：
| 检查项 | 触发时机 | 不通过的处理 |
|---|---|---|
| 干净环境一键重建 | 每次发布候选 | 阻塞发布 |
| 版本号、构建号唯一单调，命名合规 | 每次构建 | 构建失败 |
| 发布档无调试后门与作弊入口 | 发布档构建 | 阻塞发布 |
| 签名验证通过 | 打包后 | 拒绝上传 |
| 冒烟测试（启动、新档、存档、退出） | 每次构建 | 阻塞分发 |
| 目标设备抽测 | 发布候选 | 阻塞上架 |
| 归档四件套齐全 | 分发前 | 阻塞分发 |
验收看四件事，全部可观察：
- 任意一个发过的版本，当天能取出它的产物与对应提交，并能重建。
- 版本台账与商店后台的线上版本一一对应，没有「查无此包」。
- 回滚演练走过至少一次，负责人能在约定时限内把上一个稳定版本还原到测试渠道。
- 全流程手动介入次数为零：从参数注入到上传渠道，没有人需要「帮一下」。
给自己看的三个指标：手工介入次数、构建失败率、从「决定发版」到「测试渠道可下载」的时长。手工介入一次都嫌多；后两个指标连续上升，说明流程正在腐化，先修管线再谈发版。
5. 常见坑¶
- 手工构建：只有一台开发机能出包、参数靠记忆，人一休假发布停摆；产物与提交对不上，出问题无法复现。
- 版本号混乱：手填、重号、回退；商店拒收、玩家端更新异常、客服无法定位版本，台账形同虚设。
- 证书与私钥丢失：只存在个人机器或聊天记录里，人员变动或硬盘故障，发版直接冻结（§3.5）。
- 只在开发机测过：开发机装着运行库、留有历史文件，换台机器启动就崩；干净构建机加冒烟测试是底线（§3.3）。
- 发布档留后门：调试面板、作弊指令、详细日志没关，上线后被玩家发现，那是事故不是彩蛋。
- 归档缺项：产物或符号文件不齐，回滚找不到旧包、崩溃堆栈无法解析，损失都补不回来（§3.6）。
- 测试渠道与商店包不一致：测过的与发出去的不是同一构建参数，测试结论作废。
- 渠道差异散在代码里：每加一个渠道全量回归；差异应集中在打包层的配置（§3.4）。
- 密钥或证书进代码库：一次仓库泄漏，安全与身份双失；凭证永远不进版本库（§2）。
延伸阅读¶
- 《技术实现手册》：工程基础设施、构建系统与「先测量」方法论，本页是其发布侧的切面。
- 《制作管理手册》：里程碑、冻结与验收流程，发布窗口与第 4 节验收直接衔接。
- 《全平台上架手册》：商店提审、资质与合规的完整流程，与本页构成「工程到上架」的接力。
- 《避坑大全》：发布与协作类坑位速查，与第 5 节对照阅读。