ComfyUI 启动日志逐行读懂：八行关键信息与 VRAM 状态机

2026-08-09

绝大多数人贴 ComfyUI 的日志时，只贴最后那段红色的 traceback。但真正决定这台机器上 ComfyUI 怎么跑的信息，都在启动那二十来行里——它把显存总量、当前处于哪个 VRAM 状态、有没有启用 pinned memory 和异步卸载、xformers 是哪个版本，全都打出来了。你要是不认识这几行，排查显存问题基本只能靠换参数硬试。

这篇按 ComfyUI v0.31.0（2026-08-08）的 comfy/model_management.py 与 comfy/cli_args.py 的源码文案，把最值得认的八行日志逐条拆开，顺带把「日志到底输出到哪儿」「怎么把日志打详细」这两个前置问题解决掉。

现象：日志根本没落到你以为的地方

先说一个特别常见、又特别浪费时间的坑。

很多人排查时习惯写 python main.py > comfy.log，然后发现 comfy.log 是空的或者少了一大截，于是开始怀疑是不是进程没起来。不是。在 v0.31.0 的 comfy/cli_args.py 里，--log-stdout 这个参数的 help 写得很清楚：它的作用是把正常进程输出送到 stdout，而默认是 stderr。

也就是说，默认情况下你用 > 只重定向了 stdout，那些日志走的是另一条管子。判定动作很简单：

# 方式一：把 stderr 一并重定向（通用 shell 做法，与 ComfyUI 无关）
python main.py 2>&1 | tee comfy.log

# 方式二：让 ComfyUI 把正常输出改走 stdout
python main.py --log-stdout > comfy.log

两种都能拿到完整日志。第一种不依赖 ComfyUI 的参数，第二种是官方给的开关。我个人偏好第二种，因为一旦你要把日志接给别的工具做管道处理，stdout 那条路更顺。

把日志打详细：`--verbose` 的三种用法和六个等级

--verbose 在 v0.31.0 里的形态比大多数人想的灵活。它接受三种写法：

不带值：--verbose，此时等价于 DEBUG；
给一个等级：--verbose DEBUG，控制台按这个等级输出；
给等级加文件：--verbose DEBUG comfy-debug.log，把这一路输出写到文件。

而且它可以重复使用，用来增加输出目标。控制台的最终等级，取所有「没有指定文件」的那些输出里最详细的一个；如果你一个都没给，控制台默认是 INFO。

合法等级常量是六个：DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL。注意这里有个容易被忽略的成员——DETAIL。它来自 v0.30.0 的「可配置 DETAIL 日志侧通道」（PR #15064），属于比较新的等级，老教程里不会提。写错组合的时候，报错文案是 expects no values, a console LEVEL, or LEVEL FILE，看到这句就是参数形态写错了，不是环境问题。

一个可直接抄的排查启动写法：

python main.py --log-stdout --verbose DEBUG comfy-debug.log --verbose INFO

意思是：控制台保持 INFO 不刷屏，同时把 DEBUG 级别的全量输出落到 comfy-debug.log 里备查。以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 python main.py --help 的实际输出为准。

八行关键日志逐条读

下面这张表是 v0.31.0 源码里的原始格式串，不是我改写过的措辞。认这几行就够应付大部分显存类问题了。

日志文案（格式串）	它在告诉你什么
`Total VRAM {:0.0f} MB, total RAM {:0.0f} MB`	启动时探测到的显存与内存总量
`Set vram state to: {vram_state.name}`	当前 VRAM 状态机取值
`Enabled pinned memory {}`（单位 MB）	启用了 pinned memory 及其上限
`Using async weight offloading with {} streams`	异步权重卸载已启用及流数
`Requested to load {模型类名}`	开始加载某个模型
`{N} models unloaded.`	卸载了 N 个模型
`Disabling smart memory management`	对应你加了 `--disable-smart-memory`
`xformers version: {版本}`	检测到的 xformers 版本

第一行 Total VRAM ... total RAM ...，用来核对 ComfyUI 眼里的硬件和你以为的是不是同一套。多卡机器上尤其要看：如果你加了 --cuda-device，其它设备会直接不可见；而 --default-device 只是改默认设备 id，其它设备仍然可见。这两个参数的差别就是 help 里写明的「不可见」与「仍然可见」，选错了哪一个，你后面看到的所有显存现象都会跟着一起偏。至于这行数字在多卡下具体怎么呈现，源码文案没有再往下说，别拿它反推设备可见性。

第二行 Set vram state to: 是整段日志里信息密度最高的一行。 后面那个名字直接来自源码枚举：

class VRAMState(Enum):
    DISABLED = 0    #No vram present: no need to move models to vram
    NO_VRAM = 1     #Very low vram: enable all the options to save vram
    LOW_VRAM = 2
    NORMAL_VRAM = 3
    HIGH_VRAM = 4
    SHARED = 5      #No dedicated vram: memory shared between CPU and GPU but models still need to be moved between both.

六个取值，加上另一个设备状态枚举 CPUState（GPU = 0; CPU = 1; MPS = 2）。源码注释只给到这个粒度：DISABLED 是没有显存、不需要把模型搬到显存；NO_VRAM 是显存极小、把所有省显存的选项都打开；SHARED 是没有独立显存、CPU 与 GPU 共用内存但模型仍然要在两边搬。LOW_VRAM、NORMAL_VRAM、HIGH_VRAM 三个在源码里没有附注释，所以我也不去替它编「每个状态具体会做哪些动作」——你只需要拿这一行确认自己当前落在哪一档，然后回头核对是不是自己加的参数把它改到了意料之外的档位。

这里要提醒一句：就本文核对的这批日志文案而言，没有哪一行会直接宣告 dynamic VRAM 开没开。要判断它，只能按 comfy/cli_args.py（v0.31.0）里的判定函数倒推：

def enables_dynamic_vram():
    if args.enable_dynamic_vram:
        return True
    return not args.disable_dynamic_vram and not args.highvram and not args.gpu_only and not args.novram and not args.cpu

翻译成人话：什么参数都不加时，dynamic VRAM 是开的；而 --highvram、--gpu-only、--novram、--cpu 这四个里只要用了任意一个，它就被顺带关掉了。这个连带效果在各自的 help 文本里都没写，属于反直觉的地方。顺便说一个更反直觉的：--lowvram 的 help 原文是「如果启用了 dynamic vram，这个选项不做任何事」——老教程那句「显存小就加 --lowvram」在当前版本默认配置下基本是空转。

第三行 Enabled pinned memory 报的是 pinned memory 的上限。这个上限在不同系统上算法不同：Windows 上是 ram * 0.40，源码注释写的是 # Windows limit is apparently 50%；其它系统的公式还会把 swap 总量算进来，并留出 4GB / 16GB 两道余量。相关地，源码里有 Could not get amount of swap memory on system. 和 Could not read Windows swap usage; falling back to RAM-pressure pin eviction: %s 两条告警——看到它们不用慌，这是官方预期内的情况，会退回按 RAM 压力做 pin 淘汰。另外，v0.31.0 的 release note 里有一条「Don’t pin too much memory on Linux systems with no swap partition.」（PR #15266），所以「Linux 无 swap 分区」这个组合在早于 2026-08-08 的版本上是踩过坑的。想关掉这一路，参数是 --disable-pinned-memory。

第四行 Using async weight offloading with N streams，对应 --async-offload。它的 help 明确写着在 NVIDIA 上默认启用，不带参数时是 2 个流。所以你没加任何参数却看到这一行，是正常的，不是谁偷偷改了配置。关闭用 --disable-async-offload。

第五、六行 Requested to load {类名} 与 {N} models unloaded. 是加载/卸载路径的骨架。看这两行的节奏比看内容更有用：正常情况下它们成对出现；如果日志停在某个 Requested to load 之后再无下文，那就是卡在加载阶段而不是推理阶段，排查方向完全不同。社区里有一条对得上的线索——官方仓库 issue #13730 反映了「LTX 2.3 FP8/Q4KM 在 RX 7900 XTX + ROCm 上会在 Requested to load LTXAV 处停住，除非把 dynamic VRAM / pinned memory / async offload 关掉」这一现象，创建于 2026-05-06，标签为 Potential Bug，截至 2026-08-09 仍为 open。请注意 Potential Bug 的字面含义是「疑似 bug」，不是官方已确认；我们也没有读过这条 issue 的正文与评论，所以不要指望这里有现成的复现步骤或修复方案。

第七行 Disabling smart memory management 是纯粹的回声——只有你加了 --disable-smart-memory 才会出现。该参数的 help 原意是「强制积极地卸载到常规内存，而不是能留在显存时就留着」。如果你没加却看到这一行，那就去查启动脚本、桌面快捷方式或者容器的 entrypoint，一定是某处替你加上了。

第八行 xformers version: 平时没人看，出黑图时它是头号线索。源码在检测到问题版本时会输出「WARNING: This version of xformers has a major bug where you will get black images when generating high resolution images.」并提示「Please downgrade or upgrade xformers to a different version.」。高分辨率出黑图 + 日志里有这条告警，等于官方明确指向了 xformers 版本问题。

处置后怎么验证

改完参数别急着跑图，先看日志有没有按预期变化，这一步能省掉大量无效重试：

确认日志本身完整。用 --log-stdout 或 2>&1 之后，先确认 Total VRAM ... total RAM ... 那行在文件里，在了才说明你抓的是全量输出。
确认 Set vram state to: 落到了你想要的档。这是判断参数有没有真的生效最直接的一行。
确认开关的回声行出现或消失。加了 --disable-pinned-memory 就该看不到 Enabled pinned memory；加了 --disable-async-offload 就该看不到 Using async weight offloading；加了 --disable-smart-memory 就该看到 Disabling smart memory management。三条对不上，说明参数没传进去，而不是「参数没用」。
把详细日志留档。--verbose DEBUG comfy-debug.log 存一份，下次对比两个版本的启动行为时，diff 一下比回忆靠谱得多。

什么情况说明不是这一层的问题

这一节才是这篇相对「报错大全」的增量，别跳。以下几种情况，说明问题不在启动日志这一层，继续在这几行上折腾是浪费时间：

出黑图，但日志里没有那条 xformers 告警。 那就别往 xformers 上赖。在 v0.31.0 的参数表里，官方唯一明确关联黑图的开关是 --fp16-vae，它的 help 注明 might cause black images。除此之外的黑图成因，官方文档里没给，我也不替它猜。
卡在 Requested to load，但你既没开 dynamic VRAM 相关路径、也不是 AMD + ROCm 的组合。 那 issue #13730 的场景就对不上，别照着它的关闭组合乱试一遍，那只会让你多出三个不知道有没有副作用的参数。
改一次 prompt 就重新加载一次模型。 这属于另一条线：官方仓库 issue #14618 反映了「ComfyUI keeps loading models on every prompt change」这一现象，创建于 2026-06-24，标签为 Potential Bug，截至 2026-08-09 仍为 open。它是当前评论数最高的开放 issue 之一。这不是你日志读错了，也不是某一行日志能解释的。
日志里反复出现内存泄漏提示。 源码里的原文是 Potential memory leak detected with model {类名}, doing a full garbage collect, ...，更严重时是 WARNING, memory leak with model {类名}. Please make sure it is not being referenced from somewhere.。这两条几乎总是指向自定义节点持有了模型引用，官方文案给的方向就是「避免循环引用 / 检查谁还在引用它」。这时候正确动作是用 --disable-all-custom-nodes 做二分排查（必要时配合 --whitelist-custom-nodes 逐个放行），而不是继续调显存参数。
参数全都对，行为还是每两周变一次。 这是 ComfyUI 的常态。参数、默认值和日志文案都会随版本变，任何写死结论的教程（包括这篇）都只在它标注的版本上成立。真要确认，python main.py --help 的当场输出永远比文章权威。

延伸阅读

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