跳到主要内容

CLI 快速开始

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

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

设置终端命令​

打开帮助 ▸ 命令行工具 ▸ 添加到 PATH，然后关闭并重新打开终端应用。注册仅对当前用户生效，之后可直接运行 resprite-cli，无需填写应用路径。

  • macOS / Linux：自动设置支持 Bash、Zsh 和 Fish。
  • Windows：将安装目录中的 cli 加入用户 PATH，保留已有条目，无需管理员权限。新终端仍使用旧 PATH 时，可注销并重新登录。
  • Linux AppImage：注册命令会调用原始 AppImage，并自动补上 --cli。请将 AppImage 保留在固定位置。

不设置 PATH 时，可以使用下方的完整路径调用示例。

准备第一次导出​

  1. 在自己的项目目录中，将工程保存为 hero.resprite。
  2. 完成 PATH 设置后，在该目录打开新的终端。也可以从帮助 ▸ 命令行工具拷贝完整命令。
  3. 确认输出父目录已存在，且首次执行时没有 hero.png，再运行：
resprite-cli export image "hero.resprite" --output "hero.png" --frame 0

使用这组相对路径时，hero.png 会生成在源工程旁。没有注册 PATH 时，使用下方对应平台的完整路径示例。

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。动画目录使用不同的覆盖规则。

路径与后续示例​

应用移动或改名后，在帮助 ▸ 命令行工具中使用修复注册。卸载应用或切换安装版本前，使用移除注册。注册不会覆盖冲突命令或另一个仍可用的安装；移除只清理本功能创建的条目，手动配置的 PATH 仍由你管理。

工程、导出结果和自定义脚本应放在自己的项目目录中，安装目录内容可能随升级被替换或随卸载被移除。使用完整路径调用时，应用移动后需要同步更新脚本路径。

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

其他指南中的 resprite-cli 可在完成 PATH 注册后直接运行。如果使用完整路径示例设置了 $cli，则应将 resprite-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，便于向支持人员提供诊断信息。