ComfyUI 的 `--lowvram` 为什么不管用了

2026-08-09

本文口径为 ComfyUI v0.31.0（2026-08-08）时点的 comfy/cli_args.py 与 comfy/model_management.py。ComfyUI 的版本节奏很快，参数与默认值都会变，具体请以你本地 python main.py --help 的输出为准。

一、现象：加了 `--lowvram`，行为跟没加一模一样

这是一个很容易被当成「玄学」的场景。你显存吃紧，翻到一篇写得挺认真的教程，照着在启动命令后面加了 --lowvram，然后发现：启动没报错，参数也确实被接收了，但显存曲线、加载行为、报错位置跟不加的时候看不出任何差别。于是你开始怀疑是不是版本装错了、是不是环境有问题、要不要干脆上 --novram。

先把结论摆在前面：在 v0.31.0 的 comfy/cli_args.py 里，--lowvram 的 help 原文是——「如果启用了 dynamic vram，这个选项不做任何事。在没有用 dynamic vram 时，它让文本编码器跑在 CPU 上」。而在默认配置下，dynamic VRAM 恰恰是启用的。

也就是说，你什么参数都不加、直接 python main.py，再加上一个 --lowvram，官方源码的语义就是：这个开关命中的是「什么都不做」那条分支。它不是没生效，是它的设计本来就是在这种情况下不生效。这个设计相当反直觉——一个还留在 --help 输出里、名字又这么醒目的参数，默认情况下是个空操作。

二、怎么确认自己撞上的就是这件事

不要靠感觉，有三个可执行的动作。

动作一：把 dynamic VRAM 的判定函数在自己的启动命令上过一遍。 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

逐条拆开读，逻辑其实非常简单：

只要你显式写了 --enable-dynamic-vram，直接返回 True，后面全都不看；
否则要同时满足五个「没有」才算开启：没有 --disable-dynamic-vram、没有 --highvram、没有 --gpu-only、没有 --novram、没有 --cpu。这五个里任意一个出现，dynamic VRAM 就是关的。

注意这份名单里没有 --lowvram。所以 --lowvram 自己关不掉 dynamic VRAM——它只是被 dynamic VRAM 架空的那一方。现在拿你自己的启动命令去对：如果里面除了 --lowvram 之外，上面那五个一个都没有，那 dynamic VRAM 就是开的，--lowvram 按 help 的说法就是不做任何事。这就是你要找的答案。

动作二：看启动日志里的 VRAM 状态那一行。 comfy/model_management.py 在启动时会打印 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.

把加 --lowvram 和不加 --lowvram 两次启动的这一行抄下来对比，是最省事的判定动作。同一行日志附近还有 Total VRAM {} MB, total RAM {} MB，可以顺手记下你这台机器的基数，后面调参用得上。这里只做一件事：确认状态名有没有因为你加的参数而改变。至于每个状态背后具体会做哪些动作，源码注释就给了上面那么多，别脑补更多。

动作三：去掉参数再跑一次。 这条最直接——把 --lowvram 从命令里删掉，其余不动，重新启动。如果日志和行为都和之前完全一致，那这个参数在你的配置下就是空转，可以直接从启动脚本里删掉，不用再纠结。

三、为什么老教程会失效

这不是教程作者当年写错了。ComfyUI 的显存管理这一年里换过路子：v0.23.0（2026-06-01）引入了多线程从磁盘加载模型并支持 offload 到磁盘（PR #13802），v0.30.0（2026-08-03）改成用 pinning 基础设施、以 MRU 策略把权重加载到进程 RAM（PR #15027），v0.31.0（2026-08-08）又修了「Linux 无 swap 分区时不要 pin 太多内存」（PR #15266）。

dynamic VRAM 这条新路成为默认之后，老的那套「按估算决定模型怎么放」的加载方式退到了 --disable-dynamic-vram 后面——它的 help 原文就是「关闭 dynamic VRAM，改用基于估算的模型加载」。--lowvram 属于旧路径上的调节手段，新路径接管之后它自然就没有落脚点了。教程没变，底下的东西变了。

顺带一个更容易踩的坑：--highvram 的 help 只说「默认模型用完后会卸载到 CPU 内存，此选项让它们留在 GPU 内存」，一个字没提 dynamic VRAM。但按上面那个判定函数，--highvram 出现即意味着 dynamic VRAM 关闭。也就是说，你为了「多占点显存提速」加了 --highvram，实际上顺手把自己退回了估算式加载。--gpu-only、--novram、--cpu 三个也一样，都是 help 文本之外的连带效果。

四、真正该动的是哪几个参数

在 dynamic VRAM 开着的默认状态下，v0.31.0 里跟显存余量直接相关、且 help 语义明确的独立参数是这几个：

参数	默认	help 原意
`--reserve-vram GB`	None	给操作系统/其它软件保留的显存量。默认会按操作系统保留一定量
`--vram-headroom GB`	0	让 DynamicVRAM 在默认之上额外保持的空闲显存。ComfyUI 会尽量保持这么多显存完全空闲，即使是被其它应用占用的显存也计入
`--disable-dynamic-vram`	flag	关闭 dynamic VRAM，改用基于估算的模型加载
`--enable-dynamic-vram`	flag	在默认不启用的系统上启用 dynamic VRAM

怎么选，按处境倒推：

如果你的目标是「给别的程序（浏览器、录屏、另一个推理进程）留出显存」，那是 --reserve-vram。这里有个 Windows 用户必须知道的细节：源码里保留量常量 EXTRA_RESERVED_VRAM 默认是 400MB，Windows 上是 600MB，源码注释原文写的是 #Windows is higher because of the shared vram issue。而一旦你显式给了 --reserve-vram，这个值就直接变成你指定的 GB 数，也就是默认那套按操作系统区分的逻辑完全由你接管。所以在 Windows 上手写这个参数时，别填得比默认还低。

如果你的现象是「显存看起来还有余量却仍然出问题」，可以试 --vram-headroom。它和 --reserve-vram 的区别在 help 里写得很清楚：headroom 是在默认之上额外保持的空闲量，而且被其它应用占用的显存也计入这个「空闲」的核算。桌面上还开着别的吃显存的程序时，这条比单纯调 reserve 更贴合实际。

如果你就是想要老教程描述的那套行为，那就明确写 --disable-dynamic-vram，此时 dynamic VRAM 关闭，--lowvram 才回到它 help 里描述的另一半语义——让文本编码器跑在 CPU 上。这是本文唯一能给出的「--lowvram 仍然有意义」的场景：它必须和一个会关闭 dynamic VRAM 的开关配合，才不是空操作。

一个按官方参数语义组合的示例：

python main.py --reserve-vram <GB> --vram-headroom <GB>

以及「明确退回旧行为」的写法：

python main.py --disable-dynamic-vram --lowvram

以上为按官方参数语义组合的示例，未逐项实测，以官方文档与 --help 输出为准。两处 <GB> 该填多少，官方 help 只写了单位是 GB、没有给任何推荐值，所以这里也不替你填一个看起来很专业的数字——它取决于你这台机器上还同时跑着什么。

还有两个相关开关值得知道：--async-offload [NUM_STREAMS] 不带参数时是 2 个流，help 明确写「在 NVIDIA 上默认启用」，启用时日志里会打印 Using async weight offloading with {N} streams；--disable-pinned-memory 用来禁用 pinned memory，而 pinned memory 启用时日志里对应的是 Enabled pinned memory {}（单位 MB）。这两个开关跟权重在显存与内存之间怎么搬运有关，不是本篇主线，先记住它们在日志里长什么样就够了——排查时它们是你判断「这次启动到底走了哪条路径」的旁证。

五、改完怎么验证

验证不要看「感觉快了没有」，看三处确定的东西：

启动日志的 Set vram state to: 那一行有没有变。 加 --disable-dynamic-vram --lowvram 前后各抄一次，状态名不同才说明开关真的换了分支。
Total VRAM {} MB, total RAM {} MB 这一行作为基线，配合系统的显存监控看空闲量是否符合你给 --reserve-vram / --vram-headroom 的预期方向。注意是看方向，不是看某个精确数字对不对得上。
加载相关的日志行是否还在同一处停住或报错。 Requested to load {模型类名} 和 {N} models unloaded. 是源码里现成的两条格式串，用它们定位问题发生在加载阶段还是之后。

如果三处都毫无变化，说明你改的开关在你的配置下同样没落到实处，回到第二节重走一遍判定函数。

六、什么情况说明问题不在这条线上

这一节是本文最该看的部分——别一条道走到黑。出现下面这些情况，你的问题跟 --lowvram 失效没关系，继续调它是浪费时间：

你加了 --highvram、--novram、--gpu-only 或 --cpu 中的任何一个。 那 dynamic VRAM 本来就是关的，--lowvram 在你这儿并不是空操作，现象另有原因。

你的现象是高分辨率下出黑图。 官方在源码里明确关联的两个方向都不在这条线上：一是 --fp16-vae，它的 help 直接注明 might cause black images；二是 xformers 版本，comfy/model_management.py 里对问题版本会打印告警「WARNING: This version of xformers has a major bug where you will get black images when generating high resolution images.」并提示降级或升级 xformers。日志里有这条，就照它说的方向去查，不要绕到显存参数上。

日志里出现内存泄漏提示。 源码里的原文是 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，而不是继续调显存开关。

你的现象是「改了 prompt 就整个重新加载模型」。 这条社区有对应线索：官方仓库 issue #14618 反映了「改动 prompt 后每次都重新加载模型」这一现象，创建于 2026-06-24，标签为 Potential Bug，截至 2026-08-09 仍为 open。这里要说清楚两件事：Potential Bug 的字面含义是「疑似 bug」，不等于官方已确认；该 issue 至今仍是开放状态，也就是没有被标记为已修复。这类现象跟缓存策略的关系更近（默认是 --cache-ram 这套 RAM 压力缓存），不是 --lowvram 能影响的范围。

你的现象是明确的 OOM 崩溃且发生在特定版本之后。 社区侧有 issue #15255，创建于 2026-08-03，标签 Bug，截至 2026-08-09 仍为 open，标题里把它标注为「regression after Aug 3 2026 update」。同样是疑似、开放状态，我们没有读过它的正文与评论，这里只作为「你不是唯一一个」的线索给出，不能当成结论或解决方案。真要排查，先按第五节的三处日志把问题定位到具体阶段。

你根本没看到参数生效的日志变化，但也从来没确认过用的是哪个版本。 那先把版本核清楚。--lowvram 的这条 help 是 v0.31.0 时点的原文，更早的版本上语义可能不同——这也是为什么老教程和你手里的 ComfyUI 会对不上。

延伸阅读

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