游戏客户端架构 / 系统课时
哪些资源检查最适合脚本自动做
哪些资源检查最适合脚本自动做
资源检查自动化的价值不在于把所有美术审核都交给程序,而是先拿走那些重复、确定、容易漏检的工作。本节会建立自动化边界,并实现一个可重复运行的检查脚本,用于发现命名、格式、尺寸和重复文件等常见问题。
学习目标
- 判断一项资源检查是否适合自动化
- 用脚本检查命名、扩展名、图片尺寸和重复文件
- 知道哪些质量问题仍需要人工判断
优先自动化确定性高的检查
最值得脚本化的规则有三个共同特征:输入能够被程序读取,判断标准明确,相同输入必须得到相同结论。例如文件名是否符合规范、图片是否超过 4096×4096,都不依赖审美判断。
适合自动执行的高频项目通常包括:文件名和目录路径是否合法、扩展名是否在白名单中、纹理尺寸是否超限、必需文件是否存在、内容是否重复、配置中引用的文件是否缺失。它们既可以在开发机运行,也可以放进 CI,在资源进入主分支前阻止明显错误。
相反,“角色轮廓是否有辨识度”“音效是否足够有冲击力”“材质看起来是否符合世界观”没有稳定的机器判定标准,即使未来加入 AI 辅助,也更适合作为提示而不是硬性构建门禁。

一个可重复运行的检查脚本
下面的 Python 示例遍历资源目录,检查文件名、允许格式、PNG/JPEG 图片尺寸以及内容完全相同的重复文件。图片尺寸读取使用 Pillow,因此运行前需要安装依赖 python -m pip install Pillow。脚本本身只报告问题,不修改源文件,适合作为本地检查或 CI 的第一道门禁。
from __future__ import annotations
import hashlib
import re
import sys
from pathlib import Path
from PIL import Image
ALLOWED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".fbx", ".wav", ".ogg"}
NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
MAX_IMAGE_SIZE = 4096
def sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as file:
for chunk in iter(lambda: file.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def inspect(root: Path) -> list[str]:
issues: list[str] = []
hashes: dict[str, Path] = {}
for path in sorted(p for p in root.rglob("*") if p.is_file()):
relative = path.relative_to(root)
extension = path.suffix.lower()
# 命名规则只检查不带扩展名的文件名,避免大小写和空格进入资源标识。
if not NAME_PATTERN.fullmatch(path.stem):
issues.append(f"NAME {relative}")
if extension not in ALLOWED_EXTENSIONS:
issues.append(f"FORMAT {relative}")
continue
# 只有可安全读取尺寸的常规图片进入尺寸检查。
if extension in {".png", ".jpg", ".jpeg"}:
try:
with Image.open(path) as image:
width, height = image.size
if width > MAX_IMAGE_SIZE or height > MAX_IMAGE_SIZE:
issues.append(f"SIZE {relative} {width}x{height}")
except OSError:
issues.append(f"BROKEN_IMAGE {relative}")
digest = sha256(path)
if digest in hashes:
issues.append(f"DUPLICATE {relative} == {hashes[digest].relative_to(root)}")
else:
hashes[digest] = path
return issues
def main() -> int:
root = Path(sys.argv[1] if len(sys.argv) > 1 else "Assets")
if not root.is_dir():
print(f"ERROR directory not found: {root}")
return 2
issues = inspect(root)
for issue in issues:
print(issue)
print(f"checked={sum(1 for p in root.rglob('*') if p.is_file())} issues={len(issues)}")
return 1 if issues else 0
if __name__ == "__main__":
raise SystemExit(main())预期输出会随实际资源变化。例如目录中存在一个命名不规范的图片、一个超尺寸图片和一组内容完全相同的重复文件时,输出形式如下:
NAME <PATH>
SIZE <PATH> <WIDTH>x<HEIGHT>
DUPLICATE <PATH> == <PATH>
checked=<N> issues=<N>其中 <PATH>、<WIDTH>、<HEIGHT> 和 <N> 由实际扫描结果决定。脚本发现问题时返回退出码 1,没有问题时返回 0,目录不存在时返回 2,因此 CI 可以直接根据退出码决定是否继续构建。
缺失引用需要从“文件检查”升级到“关系检查”
单纯扫描目录可以判断文件是否存在,却无法知道某个场景、材质或配置究竟应该引用谁。要检查缺失引用,脚本必须获得可靠的依赖关系来源,例如项目自己的资源清单、引擎提供的编辑器 API,或者能够稳定解析的资产描述文件。
因此不要用正则表达式盲扫二进制资产,再声称已经完成引用检查。比较稳妥的做法是让各引擎适配器导出标准化依赖列表,再由通用检查器验证目标文件和资源标识是否存在。这样“通用规则”和“引擎内部资产解析”仍然保持解耦。
自动化检查应该只报告可行动的问题
检查项越多并不代表工具越有价值。如果规则经常误报,开发者很快就会忽略整个报告。一个适合进入硬性门禁的规则,应当能明确指出文件、违反的约束以及修复方向。
例如 SIZE characters/hero_basecolor.png 8192x8192 可以直接行动;而“这个纹理可能不够优化”没有明确阈值,不适合作为失败条件。对于耗时较大的重复内容哈希、模型结构解析或全项目依赖扫描,还可以分成快速检查和完整检查:提交前运行快速规则,夜间或 CI 阶段再执行完整扫描。
资源自动化最可靠的边界可以概括为:机器负责确定性事实,人负责质量判断,引擎适配器负责解析引擎内部关系。先把高频、低争议的检查做稳定,再逐步扩大覆盖范围,比一次性构建一个“什么都检查”的复杂工具更容易真正落地。