用二分法定位是哪个自定义节点的锅：`--disable-all-custom-nodes` 与白名单放行

2026-08-09

装了三十个自定义节点的 ComfyUI，某天更新完起不来了，或者能起来但一跑就报一个你从没见过的异常，日志里还夹着一条 memory leak 的告警。这时候最常见的做法是把 custom_nodes 目录挨个改名重启，试一次三分钟，二十个节点试到一半人就烦了。

其实 ComfyUI 自己带了一对参数，就是为这个场景准备的。用对了，定位一个可疑节点的次数是对数级的，不是线性级的。

现象长什么样

值得走这条排查路线的，通常是下面这几类：

启动过程中直接抛异常退出，或者启动日志卡在某一行不动了；
能起来，但网页端节点面板里少了东西，或者某个工作流一执行就报某个 Python 模块的错；
日志里出现 Potential memory leak detected with model {类名}, doing a full garbage collect, for maximum performance avoid circular references in the model code.，更严重时是 WARNING, memory leak with model {类名}. Please make sure it is not being referenced from somewhere.；
刚做完一次 git pull 或者刚在 Manager 里点了批量更新，之后就开始不对劲。

共同点是：你怀疑是插件的问题，但不知道是哪个。

先把这两个开关的语义讲清楚

在 ComfyUI v0.31.0（2026-08-08）的 comfy/cli_args.py 里，直接控制自定义节点加载行为的是下面这两个参数，help 原意分别是：

参数	help 原意
`--disable-all-custom-nodes`	不加载任何自定义节点
`--whitelist-custom-nodes NAME [NAME ...]`	在开启上一条时，仍然加载指定的自定义节点目录

第二条的措辞要读仔细：help 描述的前提是上一条已经开启。也就是说 --whitelist-custom-nodes 在官方文案里并不是一个独立的过滤器，help 只承诺了「全关 + 白名单」这一种组合下的行为，单独给它会发生什么，help 没写，我们也不替它推断。所以下面的流程里，两条一律一起给——这是二分法能跑起来的全部机制基础。

另外注意 help 里写的是「目录」。白名单里填的是 custom_nodes 下面的目录名，不是节点在界面上显示的名字，也不是仓库的 README 标题。这两者经常对不上，填错了的表现是「白名单像是没生效」，很容易被误判成参数不好使。

顺带一提，custom_nodes 属于 --base-directory 统管的六类目录之一（另外五类是 models、input、output、temp、user）。如果你为了做干净对照，用 --base-directory 指到了另一个位置，那边的 custom_nodes 大概率是空的——这时候「全关」和「全空」的效果混在一起，排查结论就不可信了。别在排查途中动目录参数。

第一刀：先确认锅在不在自定义节点这边

不要一上来就二分。先花一次启动，把问题归到「核心」还是「插件」两边。

python main.py --disable-all-custom-nodes

判定动作很直接：

起得来、现象消失 → 问题在自定义节点侧，可以继续往下二分；
现象照旧 → 到此为止，别再折腾插件了，往下翻到最后一节。

如果你的现象是执行工作流时才出现的，那么这一步还要多做一件事：全关之后，很多节点在界面上会变成红色的缺失节点，原来的工作流根本跑不完。这种情况下改用一个只包含核心节点的最小工作流去复现，别用出问题的那个原工作流去判断，否则你分不清是「问题消失了」还是「压根没跑到那一步」。

顺便说一句，这一步也是核对版本的好时机。官方 Security Advisories 里有四条公告全部发布于 2026-07-15，严重等级均为 high，修复版本均为 0.28.0，摘要分别涉及 /view 端点上传 SVG 导致的存储型 XSS、/userdata/{file} 缺少 Content-Type 处理导致的存储型 XSS、通过 /prompt API 在 LoadImage 上的路径穿越，以及 /experiment/models/preview 的路径穿越。如果你的实例还停在 0.28.0 之前，那升级本身就是一件该做的事，只是别指望它顺手治好你眼下这个报错。

第二刀开始：逐批放行

确认锅在插件侧之后，把 custom_nodes 里的目录名列成一张清单，按二分往下切。

第一轮放行前一半：

python main.py --disable-all-custom-nodes --whitelist-custom-nodes <目录名1> <目录名2> <目录名3> <目录名4>

现象复现 → 目标在这一半里，把这一半再切两半，继续；
现象没复现 → 目标在另一半里，换成后一半再来一轮。

一直切到白名单里只剩一个目录。这个流程有三条实践上的注意点：

第一，每一轮都必须用同一个复现动作。启动类问题就只看启动是否成功；执行类问题就固定用同一个工作流、同一批输入。中途换判据，二分就废了。

第二，依赖关系会制造假阳性。有些节点包会依赖另一个节点包提供的基础节点，你把 A 放行、把 A 依赖的 B 关掉，A 自己也会报错。遇到某一轮的错误信息和你原来的现象长得不一样，通常就是撞上这种情况了，把它当成噪声，别把 A 当嫌疑人记下来。

第三，日志等级调高会省下很多轮。--verbose 可以不带值、给一个 LEVEL、或者给 LEVEL FILE 两个值，合法等级是 ('DEBUG', 'DETAIL', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')，不带值等价于 DEBUG，控制台默认等级是 INFO。排查时这么写，控制台看 DEBUG，同时把日志落一份到文件里比对：

python main.py --disable-all-custom-nodes --whitelist-custom-nodes <目录名1> <目录名2> --verbose DEBUG

（DETAIL 这一级是 v0.30.0 引入的较新等级，来自「可配置 DETAIL 日志侧通道」PR #15064，老版本上没有。）

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

Windows 侧命令是一样的，区别只在于你可能不是直接敲 python main.py，而是通过启动脚本拉起来的——那就把这些参数追加到脚本里 main.py 那条命令的末尾，改完保存再跑，不要另开一个终端敲一遍，那样很容易和原来的启动方式用上不同的 Python 环境，白排查一轮。

内存泄漏告警：日志已经把方向指给你了

前面提到的两条告警值得单独说。ComfyUI 的模型管理代码在检测到模型对象该释放却没释放时，会先打 Potential memory leak detected with model {类名}, doing a full garbage collect, for maximum performance avoid circular references in the model code.，情况更严重时打 WARNING, memory leak with model {类名}. Please make sure it is not being referenced from somewhere.。

这两句文案本身就给了方向：一是避免模型代码里的循环引用，二是检查还有谁在引用它。核心代码自己的引用关系是官方在维护的，最容易出现「多留了一份引用」的地方是自定义节点（官方文案只指到「还有谁在引用它」这一层，具体是哪一处引用没放掉，要看那个节点自己的代码）。所以看到这两行，直接进入上面的二分流程是合理的第一反应，而且这次你有一个额外的抓手：告警文案里带的是模型的类名，你可以按「哪些节点和这类模型打交道」先排一下二分的顺序，把它们放到前面几轮去试。这只是调整试的顺序，判定还是得靠二分本身。

要说清楚的是，官方文案给的是方向，不是结论。这两行不构成「某个具体节点有 bug」的证据，二分跑完能稳定复现，才算定位。

定位到之后怎么验证

找到嫌疑目录之后，别急着删。做两次确认：

正向确认：只放行这一个目录，看现象是否复现。

python main.py --disable-all-custom-nodes --whitelist-custom-nodes <嫌疑目录名>

反向确认：把其余全部放行、唯独不放它。如果目录不多，把剩下的目录名都写进白名单跑一轮；现象消失，说明结论闭环了。

两次都对上，才算真的定位到。只做正向那一次是不够的——你可能只是找到了「一个也会报错的节点」，而不是「那个节点」。

确认之后的处置就回到常规套路了：看该节点仓库有没有对应你当前 ComfyUI 版本的更新，或者暂时把它从 custom_nodes 里移走。这里没有什么官方魔法参数，--disable-all-custom-nodes 和白名单是排查工具，不适合当长期运行配置——毕竟你装这些节点是有用处的。

还有一种处置方向是往回退版本而不是往前修节点。官方对分支的说法是：stable release tag 之外的 commit 可能非常不稳定，会弄坏很多自定义节点。如果你是跟着 master 最新 commit 走的，那么「一个节点忽然坏了」这件事，责任未必在节点作者那边。

什么情况说明不是自定义节点的问题

这一节是这套流程里最容易被跳过、也最容易让人一条道走到黑的部分。出现下面这些情况，就别在插件上耗了：

加了 --disable-all-custom-nodes 现象依旧。 这是最硬的一条判据。全关之后还在，就与自定义节点无关，往启动参数、版本、Python 环境三个方向查。

现象是黑图。 在 v0.31.0 的参数里，官方唯一明确和黑图关联起来的开关是 --fp16-vae，它的 help 直接注明 might cause black images。另外，源码在检测到问题版本的 xformers 时会输出「WARNING: This version of xformers has a major bug where you will get black images when generating high resolution images.」并提示升降级 xformers。先去日志里搜这行，再谈别的。

采样时看不到预览图。 --preview-method 的取值是 none / auto / latent2rgb / taesd，而源码默认是 none。所以「预览没了」的第一判定动作是确认自己启动时到底有没有加 --preview-method auto，而不是怀疑哪个插件把预览吃了。社区确实有相关反馈（issue #11400，现象为「更新到最新版后 KSampler 预览不再显示」，创建于 2025-12-18，标签为 Potential Bug，截至 2026-08-09 仍为 open）。这里要说明两件事：Potential Bug 这个标签的字面含义是「疑似 bug」，不等于官方已经确认；而且我们没有读过这条 issue 的正文与评论，所以不能断言它的根因就是这个参数。它只能说明「更新后预览不见了」这个现象有人碰到过，具体到你这台机器，还是先按上面那个判定动作走一遍。

问题只出现在网页界面上，比如按钮点不动、画布行为异常、粘贴不进图片。README 里写明前端自 2024-08-15 起迁到了独立仓库 Comfy-Org/ComfyUI_frontend，编译产物作为 comfyui-frontend-package 依赖安装，主仓库里的前端每两周更新一次而独立仓库每日发布，前端相关的 bug 与需求应该提到前端仓库。这类现象和 custom_nodes 基本无关，可以用 --front-end-version 换个前端版本对照（该参数需要联网去 GitHub releases 查询下载，默认值是 comfyanonymous/ComfyUI@latest），或者用 --front-end-root 指向本地前端目录，后者会覆盖前者。

显存不够、模型反复加载卸载这类问题。 这是显存策略参数的地盘，和插件是两条线。这里只提一个最容易踩的点：v0.31.0 源码里 dynamic VRAM 的判定是「显式 --enable-dynamic-vram 一定开，否则只要用了 --disable-dynamic-vram、--highvram、--gpu-only、--novram、--cpu 任意一个就是关」，而 --lowvram 的 help 原话是「如果启用了 dynamic vram，这个选项不做任何事」。默认状态下 dynamic VRAM 是开的，所以老教程那句「显存小就加 --lowvram」在当前版本上已经不成立了。这类问题二分自定义节点是找不到答案的。

报错信息里出现某个自定义节点的路径，但根因在核心。 前面说过 tag 之外的 commit 可能弄坏很多自定义节点。同理，Python 版本也会牵扯进来：官方在安装说明里写了 Python 3.14 能用但某些自定义节点可能有问题，也写了如果在 3.13 上遇到自定义节点依赖问题可以退回 3.12。所以「哪个节点报错」和「谁的锅」是两个问题，二分能回答前者，回答不了后者。

最后提一句风险面。社区在 issue #11791 中报告了通过 Comfy Registry 分发的名为 Upscaler_4K 的自定义节点携带 Akira Stealer 的情况，该 issue 未标注标签，创建于 2026-01-10，截至 2026-08-09 仍为 open。这不是本文的排查题材——供应链风险和「哪个节点让我报错」是两码事——但它说明 --disable-all-custom-nodes 这个开关的意义不只是调试：官方在 cli_args.py 里还给了 --disable-api-nodes（不加载所有 api 节点，同时阻止前端与互联网通信）和 --disable-manager-ui（只禁用 Manager 的 UI 与端点，计划中的安装等后台任务仍会运行）。它们是可用的收敛手段，但没有任何一条能推出「这样配置就安全了」的结论。

延伸阅读

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

安全公告信息来自 GitHub Security Advisories，本文不含漏洞利用细节。