跳到主要内容

CLI 配置与批量导出

通过 JSON 配置重复执行导出任务，或将多个工程接入项目构建流程。本文的 resprite-cli 是命令简写，请先按平台使用指南设置实际调用路径：macOS / Linux AppDir 使用 "$cli"，Windows PowerShell 使用 & $cli，Linux AppImage 使用 "$cli" --cli。

创建配置​

将以下内容保存为 build.json，与已保存的 hero.resprite、enemy.resprite 放在同一目录。按需替换工程名；不需要的任务可以从 jobs 中移除。首次执行前，三个输出目标都应不存在。

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "batch-hero.png", "frame": 0},
    {"mode": "frames", "source": "hero.resprite", "output": "batch-hero-frames"},
    {"mode": "sheet", "source": "enemy.resprite", "output": "batch-enemy-sheet", "columns": 8, "splitLayers": true}
  ]
}

配置中的相对路径以 配置文件所在目录 为基准，与终端当前目录无关；命令行直接指定的相对路径以终端当前目录为基准。输出父目录必须预先存在。

预演与执行​

在终端中进入 build.json 所在目录，先检查配置和导出计划，再正式执行：

resprite-cli batch --config build.json --dry-run
resprite-cli batch --config build.json

预演成功后仍不会生成输出。正式执行成功后，示例生成 batch-hero.png、batch-hero-frames/manifest.json 和 batch-enemy-sheet/manifest.json；后两者的图片路径见各自清单。读取方法见动画资源导出。

再次执行前，需要在想要替换输出的任务中添加 "overwrite": true。图片模式替换 PNG；序列帧和图集只能更新本 CLI 创建且内容完整的资源目录，详见覆盖规则。已有目标在预演时也需要明确允许覆盖。

若只需一个配置任务，将下面内容另存为 one-job.json，同样放在工程旁边：

{
  "schemaVersion": 1,
  "jobs": [
    {"mode": "image", "source": "hero.resprite", "output": "hero-single.png", "frame": 0}
  ]
}
resprite-cli export --config one-job.json --dry-run
resprite-cli export --config one-job.json

export --config 只接受一个任务，多个任务使用 batch。配置调用只能额外加 --dry-run，其他选项需修改 JSON，不能在命令行覆盖配置。

预演会读取工程并检查参数、输出尺寸预算、路径及已有目标，不渲染 PNG、不创建输出或输出锁。它仍需要平台指南中的运行环境。预演成功不保证正式执行时有写入权限、足够磁盘空间或可用的渲染环境；其他进程也可能在之后占用目标，正式执行会重新检查。

结果与错误处理​

通过进程 API 集成时，分别传入可执行文件路径和参数数组。 AppImage 的 CLI 参数数组需以 --cli 开始。stdout 使用 UTF-8：检查、导出、预演和正常完成的批量返回一个 JSON 对象；--help 与 --version 返回文本。诊断写入 stderr，可能混有引擎日志；不要合并两个流后解析 JSON，也不要要求 stderr 为空。

完整退出码表和输出字段见结果与退出码参考。

单任务失败或批量开始前失败时，stdout 为空，错误信息在 stderr。批量开始前会检查所有输出：不能重复或互相包含，也不能覆盖或包含源工程及配置文件；链接或大小写不同的别名也会检查。预检查失败时不执行任何任务。

通过预检查后，任务按配置顺序串行执行。参数、输入、输出或渲染错误会记录到对应任务并继续后续项；内部错误会立即中止。已成功的任务会保留产物，批量失败不会整体回滚。

正常结束的批量始终返回汇总 JSON。全部成功退出 0，至少一项失败（包括全部失败）退出 6。例如，下面是两个单帧任务中第二项失败的汇总摘录，省略了版本、路径和成功项尺寸字段：

{
  "action": "batch",
  "dryRun": false,
  "status": "error",
  "succeeded": 1,
  "failed": 1,
  "results": [
    {"index": 0, "exitCode": 0, "status": "ok"},
    {"index": 1, "exitCode": 4, "status": "error",
     "mode": "image", "code": "output_exists", "message": "Output exists; use --overwrite to replace it."}
  ]
}

index 从 0 开始，对应 jobs 的顺序。退出码 6 的失败详情在 stdout 汇总中；只读 stderr 会漏掉这些信息。

整次调用最多执行 120 秒，包含批量全部任务。超时或强制结束可能已有部分任务成功，却没有最终汇总；应按进程失败处理，核对产物后再重试，需要替换时明确启用覆盖。较大的任务集合应拆分批次。