游戏客户端架构 / 系统课时

做一条可落地的资源发布流水线

做一条可落地的资源发布流水线

一条可落地的资源发布流水线,要把“资源能提交”与“资源能进入正式构建”分开。最小闭环应覆盖命名、文件与元数据校验、导入检查、版本生成、构建和产物验收,并让每一步失败都能明确阻断发布,而不是把错误留到客户端或线上才发现。

学习目标

  • 能把资源提交到正式发布拆成可执行、可阻断的检查阶段
  • 能设计命名、依赖、版本与构建产物的最小门禁规则
  • 能让流水线产出可追溯的资源版本和验证结果

把发布拆成有明确职责的检查链

推荐的最小链路是:提交资源后先做静态校验,再做导入检查;通过后生成资源版本与清单;随后执行平台构建;最后校验产物并发布。静态校验解决“文件本身是否合规”,导入检查解决“引擎能否正确理解资源”,构建阶段解决“最终产物是否真的可发布”。

资源发布流水线

每个阶段都要回答一个明确问题:命名是否合法、引用是否闭合、导入是否成功、版本是否唯一、构建是否完成、产物是否满足发布阈值。这样失败日志才能直接指向责任边界。

先实现一个最小静态门禁

下面的脚本用标准库校验一个资源清单:路径必须小写、不能含空格,同一资源不能被分配到多个发布包,文件大小必须为正。真实项目可以继续增加扩展名白名单、目录规则、内容哈希和引用闭合检查。

python
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 个合法资源且没有重复分包时,预期输出为:

text
asset check passed: 3 assets

只要出现非法路径、零字节文件或重复分包,脚本就以非零退出码结束,CI 应直接阻断后续导入与构建阶段。

导入检查必须由真实引擎负责

静态脚本不能替代引擎导入器。纹理格式、模型骨骼、动画曲线、材质引用等问题,必须在与正式构建一致的引擎版本和导入规则下验证。这里不要自造一套“看起来像引擎”的校验逻辑,而应调用项目已经验证过的命令行构建入口或无界面导入任务。

流水线配置可以保持工具无关,只表达阶段关系。下面是一个配置片段示例,假设仓库已经提供 check_assets.py、import_assets.py、make_asset_version.py 和 build_game.py 四个脚本;它们是项目内脚本,不是第三方引擎参数。

yaml
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 与实际产物是否一致,以及最小运行验证是否通过。

一条成熟流水线的核心不是“自动执行很多命令”,而是把错误尽量前移,并让每个失败都有明确责任边界。命名错误应在静态校验阶段失败,导入错误应在引擎检查阶段失败,包体异常应在产物验收阶段失败;只有全部通过的资源批次,才进入正式发布。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

做一条可落地的资源发布流水线

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通