游戏客户端架构 / 系统课时
构建前如何自动扫描高风险资源
构建前如何自动扫描高风险资源
资源问题如果要到真机运行或打包后才暴露,修复成本已经很高。更稳妥的做法是把纹理尺寸、模型面数、依赖完整性和压缩格式转成机器可判定的规则,在构建入口前统一扫描,发现高风险项就阻止继续构建。
学习目标
- 能把常见资源风险转换为可自动执行的检查规则
- 能实现一个构建前扫描脚本,并用退出码控制构建是否继续
- 能区分应当阻断构建的错误与只需提醒的警告
把资源检查放到构建入口之前
构建前检查的关键不是“多跑一个脚本”,而是让扫描结果成为构建是否允许继续的门禁。典型链路是:资源工具先导出元数据,扫描器按规则检查,输出风险清单;只要出现阻断级问题,脚本就以非零退出码结束,后续打包步骤不再执行。

扫描器最好读取“资源报告”而不是直接绑定某个游戏引擎 API。这样 Unity、Unreal、自研引擎只需各自负责导出统一字段,后面的规则判断可以复用,也更容易在本地、CI 和构建机上保持一致。
用可判定字段描述风险
先为每类资源确定可量化字段。下面这组规则只是示例阈值,真实项目应按目标平台、画质档位和内存预算分别配置,不能直接照搬。
| 风险 | 可判定字段 | 典型处理 |
|---|---|---|
| 大纹理 | maxDimension |
超过平台上限时阻断 |
| 超高面数 | triangles |
超过单资源预算时阻断或告警 |
| 缺失依赖 | missingDependencies |
只要非空就阻断 |
| 错误压缩 | compression |
不在目标平台允许集合时阻断 |
假设资源导出器生成 asset-report.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。构建脚本只需要依据退出码决定是否继续。
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]))执行扫描:
python prebuild_scan.py asset-report.json预期输出:
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 上得到相同结论。
真正有效的构建前检查,不是生成一份没人看的报告,而是把高风险资源变成可重复、可追踪、能阻止错误进入包体的自动化门禁。