游戏客户端架构 / 系统课时
做一条可落地的资源发布流水线
做一条可落地的资源发布流水线
一条可落地的资源发布流水线,要把“资源能提交”与“资源能进入正式构建”分开。最小闭环应覆盖命名、文件与元数据校验、导入检查、版本生成、构建和产物验收,并让每一步失败都能明确阻断发布,而不是把错误留到客户端或线上才发现。
学习目标
- 能把资源提交到正式发布拆成可执行、可阻断的检查阶段
- 能设计命名、依赖、版本与构建产物的最小门禁规则
- 能让流水线产出可追溯的资源版本和验证结果
把发布拆成有明确职责的检查链
推荐的最小链路是:提交资源后先做静态校验,再做导入检查;通过后生成资源版本与清单;随后执行平台构建;最后校验产物并发布。静态校验解决“文件本身是否合规”,导入检查解决“引擎能否正确理解资源”,构建阶段解决“最终产物是否真的可发布”。

每个阶段都要回答一个明确问题:命名是否合法、引用是否闭合、导入是否成功、版本是否唯一、构建是否完成、产物是否满足发布阈值。这样失败日志才能直接指向责任边界。
先实现一个最小静态门禁
下面的脚本用标准库校验一个资源清单:路径必须小写、不能含空格,同一资源不能被分配到多个发布包,文件大小必须为正。真实项目可以继续增加扩展名白名单、目录规则、内容哈希和引用闭合检查。
import json
import re
import sys
from collections import defaultdict
VALID_PATH = re.compile(r"^[a-z0-9_./-]+$")
def main():
if len(sys.argv) != 2:
raise SystemExit("usage: python check_assets.py <manifest.json>")
with open(sys.argv[1], encoding="utf-8") as f:
manifest = json.load(f)
errors = []
bundles_by_path = defaultdict(set)
for item in manifest["assets"]:
path = item["path"]
size = item["size_bytes"]
bundle = item["bundle"]
if not VALID_PATH.fullmatch(path):
errors.append(f"invalid path: {path}")
if size <= 0:
errors.append(f"invalid size: {path}")
bundles_by_path[path].add(bundle)
for path, bundles in bundles_by_path.items():
if len(bundles) > 1:
errors.append(f"duplicate bundle assignment: {path} -> {sorted(bundles)}")
if errors:
for error in errors:
print(error)
raise SystemExit(1)
print(f"asset check passed: {len(manifest['assets'])} assets")
if __name__ == "__main__":
main()当清单中有 3 个合法资源且没有重复分包时,预期输出为:
asset check passed: 3 assets只要出现非法路径、零字节文件或重复分包,脚本就以非零退出码结束,CI 应直接阻断后续导入与构建阶段。
导入检查必须由真实引擎负责
静态脚本不能替代引擎导入器。纹理格式、模型骨骼、动画曲线、材质引用等问题,必须在与正式构建一致的引擎版本和导入规则下验证。这里不要自造一套“看起来像引擎”的校验逻辑,而应调用项目已经验证过的命令行构建入口或无界面导入任务。
流水线配置可以保持工具无关,只表达阶段关系。下面是一个配置片段示例,假设仓库已经提供 check_assets.py、import_assets.py、make_asset_version.py 和 build_game.py 四个脚本;它们是项目内脚本,不是第三方引擎参数。
stages:
- check
- import
- version
- build
check_assets:
stage: check
script:
- python tools/check_assets.py assets/manifest.json
import_assets:
stage: import
script:
- python tools/import_assets.py
make_version:
stage: version
script:
- python tools/make_asset_version.py
build_game:
stage: build
script:
- python tools/build_game.py这段配置的生效行为是:任一前置脚本返回非零退出码时,后续阶段不应继续执行。验证时应故意提交一个非法命名或缺失依赖,确认流水线确实停在对应阶段,而不是继续生成发布产物。
版本和 Manifest 要一起进入产物
每次可发布构建都应生成唯一资源版本,并归档对应 Manifest。Manifest 至少记录资源路径、内容哈希、逻辑版本、所属分包和构建目标;这样线上出现“某资源错了”时,才能从客户端版本反查到具体资源批次。
版本号不要只依赖人工填写。可以由提交号、时间戳或递增发布号组合生成,但规则必须稳定、可追溯、不可重复。资源版本与客户端版本也不要强绑定,否则只替换资源就可能被迫重新发整包。
最后验收的是产物,不是脚本成功
流水线显示绿色,只能说明各步骤执行完成,不能证明产物适合发布。发布前还要检查包体变化、缺失文件、重复资源、Manifest 与实际产物是否一致,以及最小运行验证是否通过。
一条成熟流水线的核心不是“自动执行很多命令”,而是把错误尽量前移,并让每个失败都有明确责任边界。命名错误应在静态校验阶段失败,导入错误应在引擎检查阶段失败,包体异常应在产物验收阶段失败;只有全部通过的资源批次,才进入正式发布。