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

如何用脚本批量修正资源属性

如何用脚本批量修正资源属性

一次批量修改最危险的不是“改错一项”,而是无法知道改了哪些文件、按什么规则改、失败后如何继续。本节用一个可重复执行的 Python 工具,把输入范围、修正规则、预览、日志与失败重试串成一条可审计的批处理链路。

学习目标

  • 把批处理拆成明确的输入、规则、执行和日志边界
  • 用 dry-run、幂等规则和原子写入降低批量污染风险
  • 为失败项保留可重试信息,而不是整批从头再跑

先把批处理设计成可回放的任务

安全的批处理不应该“扫描到什么就改什么”。更稳妥的做法是固定输入范围,例如指定一个资源目录或清单;规则也必须有明确版本,并且只修改自己负责的字段。这样同一批输入可以先预览,再正式执行,还能在事后重放。

一个实用流程通常包含四个环节:读取候选资源、计算差异、写入修改、记录结果。失败项只进入重试队列,成功项不再次污染。

批处理资源属性的安全执行链路

用幂等规则描述“应该是什么”

下面假设每个资源有一个同名的 .asset.json 元数据文件。规则只处理 kind 为 texture 且位于 ui 目录下的资源:关闭 mipmap,并把最大尺寸限制为 2048。规则描述的是目标状态,所以脚本重复运行时不会继续产生新变化。

示例资源元数据:

json
{
  "kind": "texture",
  "mipmaps": true,
  "maxSize": 4096
}

主脚本会先算出变更,再根据参数决定是否落盘;正式写入时先写临时文件,再用 os.replace 原子替换。每个文件的结果都会追加到 JSONL 日志,便于追踪和重试。将程序保存为 batch_fix.py,在包含 assets/ui/button.asset.json 的测试目录执行 python batch_fix.py assets;初次不要加 --apply。

python
from __future__ import annotations

import argparse
import json
import os
import time
from pathlib import Path

def desired_state(path: Path, data: dict) -> dict:
    result = dict(data)
    if data.get("kind") == "texture" and "ui" in path.parts:
        result["mipmaps"] = False
        result["maxSize"] = min(int(data.get("maxSize", 2048)), 2048)
    return result

def atomic_write(path: Path, data: dict, retries: int = 3) -> None:
    temp = path.with_suffix(path.suffix + ".tmp")
    payload = json.dumps(data, ensure_ascii=False, indent=2) + chr(10)

    for attempt in range(1, retries + 1):
        try:
            temp.write_text(payload, encoding="utf-8")
            os.replace(temp, path)
            return
        except OSError:
            if temp.exists():
                temp.unlink()
            if attempt == retries:
                raise
            time.sleep(0.2 * attempt)

def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("root", type=Path)
    parser.add_argument("--apply", action="store_true")
    parser.add_argument("--log", type=Path, default=Path("batch-log.jsonl"))
    args = parser.parse_args()

    changed = 0
    failed = 0

    with args.log.open("a", encoding="utf-8") as log_file:
        for path in sorted(args.root.rglob("*.asset.json")):
            try:
                before = json.loads(path.read_text(encoding="utf-8"))
                after = desired_state(path, before)
                if before == after:
                    continue

                changed += 1
                if args.apply:
                    atomic_write(path, after)

                record = {
                    "path": str(path),
                    "status": "applied" if args.apply else "preview",
                    "before": before,
                    "after": after
                }
                log_file.write(json.dumps(record, ensure_ascii=False) + chr(10))
                print(f"[CHANGED] {path}")
            except Exception as exc:
                failed += 1
                record = {"path": str(path), "status": "failed", "error": str(exc)}
                log_file.write(json.dumps(record, ensure_ascii=False) + chr(10))
                print(f"[FAILED] {path}: {exc}")

    print(f"summary: changed={changed}, failed={failed}, apply={args.apply}")
    return 1 if failed else 0

if __name__ == "__main__":
    raise SystemExit(main())

预期输出:

text
[CHANGED] assets/ui/button.asset.json
summary: changed=1, failed=0, apply=False

确认日志中的 before 和 after 正确后,再使用 --apply 正式写入。实际项目中应先在独立分支或可回滚工作区执行,避免直接污染主干资源。

日志和失败重试要分开设计

日志至少要记录资源路径、执行状态、修改前值、修改后值和错误信息。这样失败后可以从 status=failed 的记录生成新的输入清单,只重跑失败资源,而不是重新扫描整批资产。

不要把“重试”理解成无条件重复写入。真正可重试的前提是规则幂等、输入可定位、成功状态可识别。满足这三点后,批处理脚本才从一次性工具变成可重复执行的资产流水线能力。

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

目录与阅读设置

阅读设置

17

记录一个想法

如何用脚本批量修正资源属性

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

登录哪都通