Ludo Atlas · 管线 · 版本控制与协作基建¶
管线与工作流。定位：把代码、二进制资产与场景文件放进同一套版本控制纪律，让合入、回滚与出包都有据可查。 配套：《技术实现手册》·《制作管理手册》·《避坑大全》·《全平台上架手册》。
1. 定位与适用¶
游戏仓库是三类文件的混合体，它们的版本控制需求互相打架：
| 文件类型 | 典型例子 | 版本控制难点 |
|---|---|---|
| 源码文本 | 脚本、配置、着色器 | 可读可合并，基本不添乱 |
| 二进制资产 | 贴图、音频、模型、视频 | 不可读、不可合并，改动即整体替换 |
| 半结构化文件 | 场景、预制体、蓝图、关卡 | 名义上可读，合并极容易产生语义损坏 |
纯代码项目的默认习惯（任意开分支、任意并行、随时合并）在游戏仓库会连环出事：克隆越来越慢，冲突修不动，美术的工作被静默覆盖。这条管线的目标就是把这类事故压到接近零。
命中任意一条信号，就按加强档执行：
- 仓库超过 1GB，或干净克隆要等好几分钟；
- 团队里有人从事美术、关卡、音频工作，产物不是代码；
- 出现过「我的场景被谁覆盖了」「这个资产怎么退不回去」之类的事故；
- 需要从同一份代码出多个平台、多个渠道的包。
按规模取用：单人项目先把 §3.1 的三份清单立起来；二到十人的团队把 §3.2 到 §3.5 全部落实；十人以上再叠加集中式资产库的文件锁与更严的发布分支纪律。
三条底层原则，后续所有细节都是它们的展开：
- 仓库是唯一真源：不在仓库里的改动等于不存在，口头同步不算数。
- 可再生成的东西永不进库：缓存、导入中间产物、构建输出一律忽略，它们随时能重建。
- 大二进制文件的通道要分开：要么走 LFS，要么放集中式资产库，不能混进普通历史。
2. 工具链¶
| 环节 | 工具 | 备注 |
|---|---|---|
| 版本控制主体 | Git；重资产团队评估 Perforce 一类集中式方案 | Git 生态最广；集中式方案自带文件锁，适合美术高频并改 |
| 大文件存储 | Git LFS | 仓库里只留指针，真实内容存在独立存储区 |
| 忽略与属性清单 | .gitignore 与 .gitattributes |
全部规范的载体，随工具与资产格式演进持续维护 |
| 引擎集成 | 引擎内置的版本控制窗口与合并工具 | 让非程序成员在引擎内完成提交，减少手工操作 |
| 提交校验 | 本地钩子：提交前检查与提交信息校验 | 拦截缓存文件、超大文件与格式错误 |
| 持续集成 | 托管 CI（Actions、GitLab CI、Jenkins 类） | 最终防线：构建、测试、扫描、出包 |
| 差异与合并辅助 | 图形客户端与文本差异工具 | 降低使用门槛，处理文本类合并 |
| 备份 | 远端镜像加 LFS 对象备份 | LFS 内容不在普通克隆里，备份要单独覆盖 |
选型结论：二到五十人团队，Git 加 LFS 就够；当美术资产到达「多人每天反复改同一批大文件」的密度，再认真评估集中式方案。不要两头各搭一半，迁移成本会翻倍。
3. 流程与规范¶
日常动作固定为一句话流程：
拉取最新主干 → 开出短周期分支 → 小步提交并自检 → 推送并过合并检查 → 合回主干或打发布标签
3.1 建仓与三份清单¶
建仓当天写完三份清单，补齐它们的成本会随历史增长：
- 忽略清单：引擎缓存、导入中间产物、构建输出、日志、本地配置、系统文件。每接入一个新工具或平台，当天补条目。
- 属性清单：LFS 覆盖的格式、按平台区分的处理规则、声明为二进制的文件类型。按扩展名加路径两个维度写，宁可宽一点。
- 锁约定清单：哪些文件同一时间只允许一人改动（大场景、关键预制体、核心蓝图），以及加锁与释放的礼仪。工具能自动锁的用工具，不能的写进约定。
3.2 Git LFS 策略¶
进 LFS 的判断标准：文件不可读、体积大、每次改动整体重写。典型名单：
- 图形资产：模型、贴图源文件与成品、图集；
- 音频资产：音频工程、波形、音乐、配音；
- 视频与动效：过场、宣传素材、序列帧；
- 引擎二进制资产：引擎原生资产格式与关卡文件；
- 字体与大型数据表。
不进 LFS 的：脚本、配置、文本文档，以及小体积且频繁改动的文本格式场景文件（文本能顺畅合并时，普通管理反而更快）。LFS 名单写在属性清单里，以 .gitattributes 为准，新增格式先补条目再入库。
历史迁移的纪律：早期用普通提交混进库的大文件，彻底清理要靠重写历史；重写会让所有本地克隆失效，必须安排冻结窗口、全员通告、统一重新克隆。常见折中：只迁移确实超限的目录，接受旧历史保留一部分体积，新资产从当天起全部走 LFS。
LFS 的日常运维：
- 所有客户端与 CI 都要装好 LFS 并完成拉取，否则拿到的只是指针文件；
- 托管服务里 LFS 存储按容量与流量计费，大项目提前估算增长率；
- 备份必须覆盖 LFS 存储区，普通仓库镜像不含真实内容；
- 新增文件格式进库前，先确认属性清单已覆盖，漏一个扩展名就是一次污染。
3.3 分支策略¶
主干加短周期功能分支加发布标签，是默认答案：
| 分支或标记 | 作用 | 纪律 |
|---|---|---|
| 主干 | 唯一集成分支，随时可构建、可运行 | 不允许长期处于损坏状态，合入前自测通过 |
| 功能分支 | 单个功能或修复 | 从最新主干开出，寿命以天计，尽快合回 |
| 发布分支 | 冻结候选版本，只收修复 | 大团队与多平台场景启用，小团队可用标签代替 |
| 发布标签 | 每个对外版本的不可变快照 | 标签一旦打出不再移动，回滚以标签为准 |
配套规则：
- 版本号规则先约定，标签与安装包、商店条目、崩溃报告三方对齐；
- 切分支可能触发大规模资产重导入，把切换集中到固定窗口，或给美术准备第二份工作副本；
- 候选包从冻结分支出，验收通过才打标签；标签对应的提交不再接受新改动；
- 紧急修复从发布标签拉分支，修完同时合回主干，避免修复在下个版本里丢失。
3.4 场景与预制体冲突治理¶
半结构化文件是事故密度最高的区域，手段按优先级排：
- 约定锁：同一场景、同一预制体、同一关键蓝图，同一时间只有一人编辑，改完尽快提交并释放。成本最低，收益最高。
- 小步提交：编辑器里每完成一个有意义的改动就提交，把「一天一提交」压成「一小时一提交」，冲突面从整天缩到几分钟。
- 拆分结构：大关卡拆成子场景或分块加载，公共部分抽成独立预制体，从结构上减少多人改同一文件的机会。
- 引擎工具：合并与冲突处理优先用引擎自带功能，把语义判断交给理解文件格式的那一方；不要手工去缝文本场景的冲突标记，缝出来的文件可能能打开、能运行，但结构已经错了。
- 仲裁流程：真撞车时，指定一方放弃本地改动，由另一方按需求重建，比在冲突标记里缝补更便宜也更可靠。
提交场景与预制体时顺带确认两件事：改动是单一意图的小步改动吗？有没有引用到只有本机才有的临时资产？
3.5 提交规范与钩子¶
提交信息是仓库的叙事层，格式从第一天就用起来：
- 结构：类型前缀加一句话摘要，正文写清改动的原因与影响面；
- 类型前缀自定即可（功能、修复、美术、关卡、构建等），关键是全队统一；
- 一个提交只做一件事，功能改动与全仓格式化不混在同一个提交里；
- 写结果不写过程，「修复跨天后存档丢失」远好过「改了存档相关的东西」。
钩子的职责分工：
- 提交前检查：拦截缓存目录与构建产物、超过体积阈值的文件、不该进库的格式；
- 提交信息检查：校验格式是否符合团队约定；
- 推送前检查：可选地跑一次快速编译或冒烟测试；
- 钩子只是本地方便，可以被跳过，永远不能当安全边界；强制力放在 §4 的 CI 里。
提交前自检清单：
- 改动清单里有没有缓存、日志、临时文件？逐条对照忽略清单。
- 新增的二进制文件是否已被 LFS 覆盖？
- 场景与预制体的改动是不是小步的、单一意图的？
- 提交信息能否让半年后的自己看懂原因？
4. 自动化与验收¶
4.1 CI 触发点¶
| 触发 | 跑什么 | 目的 |
|---|---|---|
| 每次推送 | 提交信息校验、大文件扫描、忽略命中扫描、LFS 指针校验 | 把违规挡在合入之前 |
| 合并请求 | 编译、自动化测试、资源导入检查 | 保证主干随时可构建 |
| 每日定时 | 全量构建、多平台打包冒烟 | 尽早暴露配置漂移 |
| 发布标签 | 正式出包、生成发布附件与校验信息 | 让标签直接对应可分发产物 |
4.2 检查点与阈值¶
| 检查点 | 检查方式 | 参考线 | 超限处理 |
|---|---|---|---|
| 仓库体积 | 定时报告仓库与 LFS 存储增长 | 增长曲线陡增即预警 | 定位新增大户，评估迁移 |
| 单文件体积 | 推送时扫描新增文件 | 超过团队约定阈值 | 转 LFS 或压缩后重提 |
| 缓存与产物 | 提交路径与忽略清单比对 | 命中即失败 | 移除文件并补忽略条目 |
| LFS 覆盖 | 按属性清单反查新增二进制文件 | 未覆盖即失败 | 补属性条目后重新提交 |
| 提交信息 | 格式校验 | 不符合约定即失败 | 本地改好再推送 |
4.3 验收标准¶
- 新成员照仓库说明完成克隆与启动，半天以内跑通，不依赖任何口头补充；
- 任意一个发布标签，都能在一台干净机器上重建出可运行版本；
- 回滚一次发布在小时级完成，流程至少演练过一遍；
- 随机抽取若干二进制资产，能从提交历史说清来源、许可与当前版本；
- 连续一个月没有发生「覆盖他人场景」「大文件污染历史」类事故；发生一次，回到第 3 节补规范。
度量让讨论有依据：仓库体积、克隆耗时、冲突次数、LFS 流量，每月看一次，异常波动比绝对值更重要。
5. 常见坑¶
- 缓存与构建产物进库：引擎缓存、导入中间层、打包输出被提交，仓库迅速膨胀，团队互相覆盖可再生成的文件。建仓当天把忽略清单写全。
- 大文件历史污染：资产先以普通提交进库，等发现时历史已经背着几十个版本的大文件，越晚处理越贵（迁移策略见 §3.2）。
- 忽略设置滞后：新装工具、新接平台，忽略清单没跟上，垃圾文件一批批混进来。补清单与工具接入同一天完成。
- 把二进制资产当文本管：不设锁、不禁并行，两人同改一个源文件，先推送的版本把后者的工作静默覆盖。
- 手工合并文本场景：对着节点标识缝冲突标记，结果能打开但结构已错，代价远高于重建。
- 长期功能分支：分支悬空数周，合入当天变成大爆炸集成。分支寿命以天计是有原因的。
- 提交信息空洞：满屏「更新」「修复」，出问题时无法定位也无法回退。
- 只有本地钩子没有 CI：钩子可以被跳过，也可以根本没装，把校验全押在本地等于没有校验。
- LFS 只管提交不管运维：新成员克隆拿不到真实文件、配额见底、备份没覆盖 LFS 存储，问题会在半年后集中爆发。
- 凭据混进历史：令牌、密钥、账号写进配置并提交，删除文件并不能删除历史；凭据必须轮换，历史要么重写要么承担风险。
延伸阅读¶
- 《技术实现手册》：工程基建与资产管线的完整展开，本文是其版本控制部分的落地版。
- 《制作管理手册》：协作规范、QA 与发布流程的上位框架，团队规模与规范强度如何匹配看这里。
- 《避坑大全》：版本控制与协作相关坑位的合集与分级，里程碑评审时对照。
- 《全平台上架手册》：出包与发布流程，发布标签与构建流水线的下游。
- 同区邻居：《Mod 与 UGC 手册》与《联机与后端深入手册》是本管线的已发布邻居页，可对照各自的协作与工具章节。