为什么你的命令总是失败comfy-cli 结构化错误码与 JSON 输出契约实战指南30秒定位问题【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-clicomfy-cli 是 ComfyUI 官方推荐的命令行工具用于安装、运行和扩展 ComfyUI 工作流。很多新手都会遇到这样的场景一条comfy run命令失败了屏幕上只有一堆难读的堆栈信息却说不清到底错在哪。好消息是——comfy-cli 为每个命令内置了结构化错误码error code和JSON 输出契约只要给命令加上--json参数就能在 30 秒内精准定位问题根源。一、痛点人类可读输出机器却看不懂默认情况下comfy-cli 会输出带颜色的美化界面对人友好但当你想写脚本、做 CI 自动化或者只是想知道退出码 1 到底代表什么时这种输出就帮不上忙了。传统命令行工具的错误处理往往是这样的退出码只有0成功和1失败两种信息量不足错误信息混在彩色日志里没法程序化解析同一个失败可能来自路径错误、服务未启动、节点参数不合法、云端未登录……全靠肉眼猜comfy-cli 的做法是把错误分类从退出码搬进了结构化的error.code字段用注册码值来区分每一种失败。二、认识 JSON 输出契约一个统一的信封comfy-cli 的所有命令都支持--json参数。开启后标准输出stdout里只有一行纯粹的 JSON 数据没有 ANSI 颜色码、没有进度条、没有标题装饰可以放心地交给jq或任何脚本解析。这一行 JSON 就是一个信封envelope结构固定为字段含义ok布尔值命令是否成功对应退出码 0command当前子命令如runversion产生该输出的 comfy-cli 版本号where路由目标local或cloud未路由命令为nulldata成功时的结果数据失败时为nullerror失败时的错误对象成功时为null 记住一句话成功看data失败看error。信封结构在 comfy_cli/schemas/envelope.json 中有完整的 JSON Schema 定义。三、结构化错误码comfy-cli 的故障字典失败时的error对象固定包含 4 个字段定义见 comfy_cli/schemas/error.json字段作用code稳定的机器标识符如server_not_running程序分支判断只看它message人类可读的一句话错误描述hint一条可操作的下一步建议有就一定会给details结构化上下文如status、host、node_errors等帮助自动纠错这套错误码体系的设计约定记录在 comfy_cli/schemas/error_codes.md核心原则是code是契约程序分支只看code不解析message文本只增不改已注册的错误码永不被复用或改名保证脚本长期兼容全量可查运行comfy --json discover即可在data.error_codes中列出当前版本注册的全部错误码目前已有 170 个错误码的唯一事实来源是 comfy_cli/error_codes.py项目通过测试强制保证每个被抛出的错误码都必须注册每个注册码都真实存在——不允许出现死码。四、30 秒排查速查表常见错误码对照以下是日常使用comfy run时最高频的几个错误码及应对方法完整说明见 docs/json-output.md错误码code触发场景hint建议的下一步workflow_not_found--workflow路径不存在检查路径是否正确workflow_invalid_json文件不是合法 JSON从 ComfyUI 重新导出File → Export (API)server_not_running目标 host:port 上没有 ComfyUI 服务先comfy launch启动服务workflow_unknown_nodes工作流含未知节点或参数形状不匹配查看details.errors修复节点prompt_rejected服务端返回 400含逐节点校验错误检查details.node_errors并修正参数execution_error节点执行时抛异常查看details.traceback与node_idcloud_unauthorized云端任务没有有效登录态运行comfy cloud logincancelledCtrl-C 或服务端中断退出码 130非程序错误 小技巧看到execution_error时直接读details里的node_id、exception_type和traceback比翻日志快得多。五、实战三步把报错变成可诊断第 1 步给命令加--jsoncomfy run --workflow ./workflow.json --json标准输出变成纯 JSON标准错误stderr保留人类可读的补充信息——脚本只解析 stdout 即可。第 2 步用退出码做粗分类comfy-cli 的退出码映射非常克制0成功信封ok: true130任务被取消cancelled1其他所有失败——细粒度分类全部在error.code里第 3 步按error.code分支处理在 CI 脚本中你可以针对不同错误码采取不同策略server_not_running时自动拉起服务后重试prompt_rejected时把node_errors打印给开发者transient_auth临时鉴权过期则直接重新提交即可成功。六、进阶流式事件 最终信封对于comfy run --json输出其实是NDJSON 流中间每一行是一个事件queued、executing、progress、executed、output等每行带type字段用于分发最后一行才是上面的信封。这种设计的妙处在于事件行提供实时进度可驱动自定义 UI信封行给出最终裁决comfy jobs watch的监控流与run流共用同一套事件方言未识别的新事件类型直接忽略即可契约向后兼容七、延伸阅读与源码位置想了解每个事件、每个字段的完整契约建议按这个顺序读docs/json-output.md ——comfy run --json的完整输出契约含成功/失败/取消的全量示例comfy_cli/schemas/error_codes.md —— 错误码设计约定人类版说明comfy_cli/error_codes.py —— 全部注册错误码的定义处comfy_cli/schemas/error.json 与 comfy_cli/schemas/envelope.json —— 机器可读的 Schema总结comfy-cli 用两个设计把命令失败变成了可诊断、可自动化的问题JSON 输出契约stdout 纯数据、统一信封、稳定退出码结构化错误码170 个只增不改的error.code每个都带hint和details下次命令失败时别再盯着彩色日志猜了——加上--json读一下error.code30 秒内你就能知道问题出在哪、下一步该做什么。【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考