ComfyUI 日志分级、落文件与 DETAIL 等级：`--verbose` 的三种用法

2026-08-09

排查 ComfyUI 的问题，十次有八次卡在同一个地方：现象是偶发的，等你想去翻日志，控制台早就被后面几十次运行刷没了。更尴尬的是有人让你把日志贴出来，你才发现自己压根没让它落过文件。

日志这块的入口其实只有两个参数，--verbose 和 --log-stdout。参数不多，但语义比看上去绕——--verbose 一个参数承担了三种写法，还能重复给；控制台的等级也不是「你写什么就是什么」。下面这些以 ComfyUI v0.31.0（2026-08-08）的 comfy/cli_args.py 为准，参数与默认值会随版本变动。

一、`--verbose` 的三种形态

comfy/cli_args.py（v0.31.0）里，--verbose 接受的值是可变的，一共三种合法形态：

写法	含义
`--verbose`	不带值。等价于 DEBUG
`--verbose LEVEL`	给一个等级，这是一路「控制台输出」
`--verbose LEVEL FILE`	给等级加文件路径，这是一路「文件输出」

关键在最后一句：这个参数可以重复使用，每写一次就增加一个输出目标。所以「控制台一份、文件再来一份」不需要额外的开关，写两次 --verbose 就行。

合法的等级常量只有六个，源码里是这么一串：('DEBUG', 'DETAIL', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')。注意是 WARNING 不是 WARN——很多人从别的框架带着肌肉记忆过来，顺手敲了 WARN，那不在枚举里。

如果你把值的个数写错了（比如一口气给了三个），源码给出的报错文案原样是：

expects no values, a console LEVEL, or LEVEL FILE

这行文案本身就是一份速查表：它把三种合法形态按顺序念了一遍。看到它不用慌，数一下自己给了几个值就知道错在哪。

二、DETAIL 是从哪冒出来的

六个等级里，DEBUG、INFO、WARNING、ERROR、CRITICAL 是标准的那一套，DETAIL 是 ComfyUI 自己加的一级。

它来自 v0.30.0（2026-08-03）的一条 release notes 条目：新增可配置的 DETAIL 日志侧通道，对应 PR #15064。release notes 只说明「加了这个东西」，没有展开实现细节，所以这一级具体往里写哪些内容、和 DEBUG 的分工怎么划，官方那条目里没有交代，我这里也不替它编。你能确定的是两件事：一，这个等级在 v0.30.0 之后才存在，你要是还跑在更早的版本上，--verbose DETAIL 这么写没有意义；二，release notes 用的措辞是「侧通道」，至于它和 DEBUG 之间详略怎么排，官方那条目里没说，别默认它就是 DEBUG 的加强版。

顺带提醒：ComfyUI 大约每两周发一个 major stable 版本，README 里也写明了 stable release tag 之外的 commit 可能非常不稳定、会弄坏很多自定义节点。想用 DETAIL 而当前版本没有，正确姿势是升到发布过的 tag，不是去拉 master 上的某个 commit。

三、控制台等级由谁决定（这条最反直觉）

源码里的规则是这样的：控制台等级取所有「无文件」输出里最详细的一个，默认是 INFO。

拆开看有两层意思。

第一层，带 FILE 的那一路不参与控制台等级的计算。也就是说你写 --verbose DETAIL detail.log，控制台还是默认的 INFO，不会因为你要了一份 DETAIL 文件就把控制台也刷成 DETAIL。这对「后台长期开着、只想留档」的场景是好事——不少人以为一开文件日志控制台就得跟着噪，其实不会。

第二层，一旦你写了多路不带文件的 --verbose，最详细的那一路说了算。同时写 --verbose INFO 和 --verbose（等价 DEBUG），控制台就是 DEBUG。这一条决定了一件事：你没法靠再加一个更粗的等级把控制台压安静。至于给一个比 INFO 更粗的等级（比如 --verbose WARNING）能不能真把控制台调得比默认更安静，help 文本只说了「取最详细的一个、默认 INFO」，没有把默认值是否参与比较讲死。这种地方别赌，真要让控制台清净，可靠做法是只给带文件的 --verbose，一路无文件的都不写。

四、命令怎么写

场景一：临时排一个当场就能复现的问题，只要控制台更啰嗦。

python main.py --verbose

不带值即 DEBUG。临时用完就去掉，不用记等级名。

场景二：问题偶发，要留档，但不想让控制台变吵。

python main.py --verbose DETAIL /srv/comfy-logs/comfyui-detail.log

这一路带文件，按第三节的规则不影响控制台，控制台仍是默认 INFO。这里用绝对路径是有讲究的：help 只说了第二个值是 FILE，没有说明相对路径按哪个目录解析——是进程工作目录还是 ComfyUI 安装目录，我们没有依据下结论，那就别给它机会，直接写绝对路径。

场景三：控制台看大概、文件留细节、错误再单独抽一份。

python main.py \
  --base-directory /srv/comfy-data \
  --verbose \
  --verbose DETAIL /srv/comfy-logs/comfyui-detail.log \
  --verbose ERROR /srv/comfy-logs/comfyui-error.log \
  --log-stdout

逐条说为什么在这：

--base-directory 一次性设置 models、custom_nodes、input、output、temp、user 六类目录的基准目录。放这条不只是为了目录整齐——v0.26.0（2026-06-23，PR #13370）起，使用 --base-directory 时会把 base 目录打进启动日志，这给了你一个可核对的锚点，后面验收要用。
第一个 --verbose 不带值，控制台走 DEBUG，人盯着看。
第二个 --verbose DETAIL <文件> 留档 DETAIL 侧通道。
第三个 --verbose ERROR <文件> 把 ERROR 及以上单独抽一份，出事的时候不用在几十兆里翻。
--log-stdout 见下一节。

Windows 上把行尾的反斜杠换成 PowerShell 的续行符，或者干脆写成一行。

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 输出为准。

五、默认走 stderr，这是个真会咬人的细节

--log-stdout 的 help 说得很直接：把正常进程输出送到 stdout，默认是 stderr。

这句话的实际后果是：你在 shell 里习惯性地写 python main.py > comfy.log，只重定向了 stdout，日志一行都不会进这个文件——它们全在 stderr 上。这是 shell 的通用行为，不是 ComfyUI 特有的规则，但踩的人不少，因为「程序日志走 stdout」是大多数人的默认预期。

两条路：要么加 --log-stdout 让输出改走 stdout，配合你原来的重定向习惯和各种管道工具；要么干脆别用 shell 重定向，用 --verbose LEVEL FILE 让 ComfyUI 自己写文件。第二条路在 Windows 上尤其省事——把「往哪写文件」交给 ComfyUI 的参数，你就不用再去管自己开的是 cmd 还是 PowerShell、重定向该怎么敲。

如果你用 systemd、supervisor、Docker 一类东西托管，--log-stdout 通常值得加上，因为这些管理器对 stdout 和 stderr 的采集与分级处理方式往往不同。具体怎么配属于通用运维范畴，不是 ComfyUI 官方文档的内容，按你自己那套来。

六、产出物长什么样

有依据的只有这几处，其余的我不替它描述：

你给的 FILE 路径上会出现日志文件，路径由你自己指定，所以文件名不会有意外。
控制台那一路默认落在 stderr，加了 --log-stdout 后落在 stdout。
如果启动命令里带了 --base-directory，v0.26.0 起启动日志里会有一行打印出这个 base 目录。这是我们有明确依据的、唯一一条具体的启动日志内容。

至于文件里每行的格式、时间戳样式、是否带模块名，cli_args.py 的 help 没有交代，release notes 里也没有，那就以你自己启动后看到的实际输出为准。

七、怎么验收

按顺序过这四步，出错基本都在前两步：

第一步，先验参数被正确解析。 故意写一次非法组合，比如给 --verbose 塞三个值，看是否吐出 expects no values, a console LEVEL, or LEVEL FILE。看到这行说明你这个版本的参数语义就是本文说的这套；没看到（比如报了别的错、或者压根没报错）说明版本对不上，后面别照抄。

第二步，验文件真的被创建了。 启动后立刻去 FILE 指定的路径看文件在不在。最常见的失败是目录不存在或没有写权限——注意 --verbose 的 FILE 和 --user-directory、--models-directory 那种会在启动时校验路径存在且可读的参数不是一回事，别指望它用同样的方式提前拦你。

第三步，验控制台等级是不是你要的。 对照不加任何 --verbose 时的输出比一比行数和内容。如果你的本意是「控制台安静、文件详细」，却发现控制台变吵了，回头数一下命令里有没有哪一路 --verbose 忘了给文件名——按第三节的规则，那一路会把控制台顶上去。

第四步，如果用了 shell 重定向，单独验一次。 只用 > 抓不到默认走 stderr 的输出，这一步最容易在「日志文件是空的」上浪费半小时。有 --base-directory 的话，用启动日志里那行 base 目录当锚点最快：它出现了，说明这条链路通了。

八、什么情况别这么干

别长期挂着 DEBUG 或 DETAIL 落盘。 v0.31.0 的参数表里没有任何与日志轮转、切割、体积上限相关的选项，也就是说文件会一直长下去，这部分得你在运维层面自己处理。定位完问题就把这一路 --verbose 摘掉。
贴日志给别人之前先脱敏。 --base-directory 会把你的目录打进启动日志，日志里出现完整的本机路径是常事。往公开 issue 或群里贴之前，把路径里的用户名、项目名换成占位符。
版本低于 v0.30.0 就别惦记 DETAIL。 那时候还没有这一级，先升级到发布过的 stable tag 再说。
别指望日志能解决可复现性问题。 想让同一个种子出同样的结果是另一码事，--deterministic 的 help 自己就写明了「这可能并不能在所有情况下让图像可复现」。日志只负责告诉你发生了什么，不负责让它稳定重演。
需要按模块单独调等级的场景，这套满足不了。 v0.31.0 的参数表里没有按 logger、按模块分别设等级的选项，--verbose 是全局粒度的。真要那种精度，得另想办法。
挂起类问题不归 --verbose 管。 进程卡住不动、日志停在那儿的情况，--debug-hang 才是对的工具——它的定位是在 Ctrl-C 时输出栈回溯，用于调试挂起。把日志等级往上调对这类现象通常帮不上忙。

日志这块的账很好算：花五分钟把 --verbose LEVEL FILE 配上，下次出偶发问题就有据可查；不配，就只能等它再复现一次。代价只有一个磁盘上的文件，还得记得定位完就摘掉。

延伸阅读

本文依据 ComfyUI 官方仓库（github.com/Comfy-Org/ComfyUI）的 README、comfy/cli_args.py、 release notes 与官方安全公告整理，核对日 2026-08-09，对应版本 v0.31.0；文中引用的 issue 状态为该日期的快照。本文内容为官方文档与源码口径，非本机实测。参数、默认值与功能随版本变动，请以官方文档与 python main.py --help 的实际输出为准。