跳到主要内容

CLI 快速开始

Resprite CLI 可以将已保存的 .resprite 工程导出为单张 PNG、序列帧或规则图集，也支持工程检查、JSON 配置和批量导出，便于将资源导出接入项目构建流程。

CLI 目前为实验性功能。本组文档适用于 CLI 0.3.0-prototype，随 Resprite 1.32.6 的 macOS、Windows 版本提供，Linux x86_64 发行包也包含 CLI。--version 返回 CLI 版本，应用版本在“关于”中查看。

准备第一次导出​

  1. 在自己的项目目录中，将工程保存为 hero.resprite。
  2. 在 Resprite 中打开 帮助 → 命令行工具，拷贝完整命令，或选择下方对应平台的示例。
  3. 将应用和工程路径替换为实际路径。输出父目录必须已经存在；首次执行时，hero.png 应不存在。

CLI 只读取磁盘中已保存的内容，不修改源工程或编辑器中的文档、帧和选区。帧号从 0 开始。所有平台都需要可用的图形环境，执行时不显示编辑器窗口。

按平台运行​

发行包包含 Apple Silicon（arm64）和 Intel（x86_64）架构。具体 macOS 版本和硬件的兼容性仍待确认；无 GPU CI 和无交互服务会话尚未验证。

cli='/Applications/Resprite.app/Contents/MacOS/resprite-cli'
"$cli" export image "$HOME/Game Projects/hero.resprite" \
  --output "$HOME/Game Projects/hero.png" --frame 0

请保留完整 .app，不要只拷贝可执行文件。使用 "$cli" --help 查看语法，使用 "$cli" --version 查看 CLI 版本。

成功后，在源工程旁找到 hero.png。图片合成可见图层并保留透明度，终端还会输出一条 JSON 结果。之后需要替换 PNG 时，在导出命令末尾添加 --overwrite。动画目录使用不同的覆盖规则。

路径与后续示例​

安装不会将 CLI 加入 PATH。工程、导出结果和自定义脚本应放在自己的项目目录，安装目录中的内容可能随升级被替换或随卸载被移除。应用移动或改名后，更新脚本路径，也可以重新打开帮助页拷贝命令。

命令行相对路径以终端当前目录为基准，JSON 配置内的相对路径以配置文件所在目录为基准。包含空格的路径需要加引号。

其他页面使用 resprite-cli 作为命令简写。在已设置 $cli 的终端中，应替换为：

平台调用方式
macOS / Linux AppDir"$cli" ...
Windows PowerShell& $cli ...
Linux AppImage"$cli" --cli ...

帮助页还可以打开随包的平台、动画和构建流程说明，供离线阅读。使用 在文件夹中显示 定位 Markdown 文件并自行选择阅读器。

故障排查​

没有生成图片时，先检查退出码和 stderr，再确认源工程已保存、输出父目录存在且可写，以及需要替换时已明确允许覆盖。链接目标会被拒绝；文件占用和权限限制也可能导致失败。详见结果与退出码。

每次调用最多执行 120 秒，包括批量中的所有任务。超时或强制结束后，先核对可能已生成的产物，再决定是否重试。系统临时目录中可能保留 resprite_cli_*，输出父目录中可能保留 .resprite_cli_*。所有 CLI 任务停止前，不要删除锁文件或清理相关目录。

如果 macOS 拦截启动，请保留系统提示并联系支持。自检脚本不能授予启动许可或解除系统限制。

检查 macOS 安装
/bin/bash '/Applications/Resprite.app/Contents/Helpers/RespriteCLI.app/Contents/Resources/verify_macos_installation.sh'

按需替换安装路径。脚本使用 macOS 自带工具和随包示例，不需要另装开发工具，不修改安装文件或自己的工程。完成后打印 report.txt 路径，并保留示例导出及 stdout/stderr，便于向支持人员提供诊断信息。