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

构建前如何自动扫描高风险资源

构建前如何自动扫描高风险资源

资源问题如果要到真机运行或打包后才暴露,修复成本已经很高。更稳妥的做法是把纹理尺寸、模型面数、依赖完整性和压缩格式转成机器可判定的规则,在构建入口前统一扫描,发现高风险项就阻止继续构建。

学习目标

  • 能把常见资源风险转换为可自动执行的检查规则
  • 能实现一个构建前扫描脚本,并用退出码控制构建是否继续
  • 能区分应当阻断构建的错误与只需提醒的警告

把资源检查放到构建入口之前

构建前检查的关键不是“多跑一个脚本”,而是让扫描结果成为构建是否允许继续的门禁。典型链路是:资源工具先导出元数据,扫描器按规则检查,输出风险清单;只要出现阻断级问题,脚本就以非零退出码结束,后续打包步骤不再执行。

构建前资源扫描门禁流程

扫描器最好读取“资源报告”而不是直接绑定某个游戏引擎 API。这样 Unity、Unreal、自研引擎只需各自负责导出统一字段,后面的规则判断可以复用,也更容易在本地、CI 和构建机上保持一致。

用可判定字段描述风险

先为每类资源确定可量化字段。下面这组规则只是示例阈值,真实项目应按目标平台、画质档位和内存预算分别配置,不能直接照搬。

风险 可判定字段 典型处理
大纹理 maxDimension 超过平台上限时阻断
超高面数 triangles 超过单资源预算时阻断或告警
缺失依赖 missingDependencies 只要非空就阻断
错误压缩 compression 不在目标平台允许集合时阻断

假设资源导出器生成 asset-report.json:

json
[
  {
    "path": "Assets/UI/menu_bg.png",
    "type": "texture",
    "maxDimension": 8192,
    "compression": "none",
    "missingDependencies": []
  },
  {
    "path": "Assets/Characters/boss.fbx",
    "type": "mesh",
    "triangles": 180000,
    "missingDependencies": []
  },
  {
    "path": "Assets/Levels/arena.prefab",
    "type": "prefab",
    "missingDependencies": ["Assets/Textures/missing.png"]
  }
]

这份文件本身不决定构建结果,它只提供稳定输入。验证重点是字段是否由引擎导出器真实生成,并且路径、面数、压缩方式与编辑器中看到的数据一致。

实现一个最小扫描器

下面的 Python 脚本只依赖标准库。它读取资源报告,逐项执行规则,并在发现风险时返回退出码 1;没有问题则返回 0。构建脚本只需要依据退出码决定是否继续。

python
import json
import sys
from pathlib import Path

MAX_TEXTURE_DIMENSION = 4096
MAX_MESH_TRIANGLES = 100_000
ALLOWED_COMPRESSIONS = ("astc", "bc7", "etc2")

def scan(report_path: str) -> int:
    assets = json.loads(Path(report_path).read_text(encoding="utf-8"))
    problems = []

    for asset in assets:
        path = asset["path"]
        asset_type = asset["type"]

        # 纹理规则同时检查尺寸和目标平台允许的压缩格式。
        if asset_type == "texture":
            dimension = asset.get("maxDimension", 0)
            compression = asset.get("compression", "")
            if dimension > MAX_TEXTURE_DIMENSION:
                problems.append(
                    f"{path}: texture dimension {dimension} > {MAX_TEXTURE_DIMENSION}"
                )
            if compression not in ALLOWED_COMPRESSIONS:
                allowed = ",".join(ALLOWED_COMPRESSIONS)
                problems.append(
                    f"{path}: compression={compression} not in {allowed}"
                )

        # 模型面数使用三角形数量作为统一预算口径。
        if asset_type == "mesh":
            triangles = asset.get("triangles", 0)
            if triangles > MAX_MESH_TRIANGLES:
                problems.append(
                    f"{path}: triangles {triangles} > {MAX_MESH_TRIANGLES}"
                )

        for dependency in asset.get("missingDependencies", []):
            problems.append(f"{path}: missing dependency {dependency}")

    if problems:
        for problem in problems:
            print(f"ERROR {problem}")
        print(f"SCAN FAILED: {len(problems)} risk(s)")
        return 1

    print("SCAN PASSED")
    return 0

if __name__ == "__main__":
    raise SystemExit(scan(sys.argv[1]))

执行扫描:

bash
python prebuild_scan.py asset-report.json

预期输出:

text
ERROR Assets/UI/menu_bg.png: texture dimension 8192 > 4096
ERROR Assets/UI/menu_bg.png: compression=none not in astc,bc7,etc2
ERROR Assets/Characters/boss.fbx: triangles 180000 > 100000
ERROR Assets/Levels/arena.prefab: missing dependency Assets/Textures/missing.png
SCAN FAILED: 4 risk(s)

此时进程退出码为 1,构建入口应立即停止。如果报告全部通过,脚本输出 SCAN PASSED 并返回 0。

阈值要能随平台和项目演进

同一个资源在 PC、主机和移动端的风险等级可能完全不同,因此不要把阈值永久写死在扫描逻辑里。实际工程中更适合把“规则实现”和“平台阈值”分离,例如为 Android、iOS、PC 分别提供配置,再由构建目标选择对应配置。

另一个实用策略是优先扫描本次变更涉及的资源,同时保留定期全量扫描。前者保证提交和构建反馈足够快,后者负责发现跨资源依赖、全局预算和长期积累的问题。

构建门禁的验收标准

接入完成后,至少验证四件事:故意放入一张超尺寸纹理时构建会失败;恢复后重新构建可以通过;缺失依赖不会被“警告后继续”;同一份资源报告在开发机和 CI 上得到相同结论。

真正有效的构建前检查,不是生成一份没人看的报告,而是把高风险资源变成可重复、可追踪、能阻止错误进入包体的自动化门禁。

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

目录与阅读设置

阅读设置

17

记录一个想法

构建前如何自动扫描高风险资源

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

登录哪都通