ComfyUI 排障速查：红节点、启动卡死、VAE 发灰与更新回退

打开别人分享的 workflow，一排红色 unknown nodes——你点了 Manager 的 Install Missing Custom Nodes，重启后仍然红。Manager 不是万能的，它只负责管理节点代码，不保证每个节点的依赖都能自动装好，也不负责模型文件。

红节点只是 ComfyUI 排障的入口之一：启动卡在 loading、白屏进不了 UI、更新后原来能跑的工作流崩了、VAE 输出发灰或全黑、模型放进去了但 dropdown 不出现——这些症状的背后，往往是 custom node 冲突、依赖版本问题、模型路径配置、精度参数或显存峰值。

这篇文章按症状分类给出排障入口：匹配症状，判断原因，知道先做什么。

首屏症状速查表

下表覆盖 ComfyUI 排障的六大入口症状。看到哪个症状，先按对应行判断最可能原因，再跳到具体章节处理。

症状	最可能原因	先做什么
红节点 / unknown nodes	缺 custom node、节点改名或节点加载失败	用 Manager / Registry 查节点名，并看终端是否有 Import failed
启动卡 loading / 白屏 / blank screen	前端 custom node extension 冲突	用 python main.py --disable-all-custom-nodes 启动测试
点 Queue 后报错 Prompt execution failed	custom node 错误 / 模型问题 / VRAM 不足	点 Show report 读详细报错，判断报错来源
VAE 输出发灰 / 发白 / 偏色 / 全黑	VAE 精度参数或错配	检查 VAE loader 连接、VAE 文件匹配、--fp16-vae 参数
更新后原来的 workflow 崩了	core / custom node 版本冲突或依赖问题	判断只更新了哪一部分，看 update 文件夹脚本
模型放进去了，dropdown 不出现	模型路径错误或未刷新	检查 ComfyUI/models/ 子目录，重启或刷新节点定义

判断顺序：先用第一列匹配症状，再用第二列判断问题来源，最后按第三列跳到对应章节。

红节点分诊：缺 custom node 还是缺模型？

红节点（unknown node）通常意味着 ComfyUI 找不到这个节点类型的定义，常见原因包括缺 custom node、节点改名、节点依赖加载失败或节点被禁用。模型文件缺失通常表现为 loader 的 dropdown 找不到文件，或执行时报告模型问题，不要把两类故障混为一谈。

1. Manager Install Missing 能解决哪些？

ComfyUI-Manager 的 Install Missing Custom Nodes 主要解决节点代码缺失。它通过 Registry 或代码仓库安装节点，但以下内容不一定自动处理成功：

• 节点的 Python 依赖（requirements.txt 里的 torch、numpy、xformers 等）
• 模型文件（checkpoint、VAE、LoRA、ControlNet）
• custom node 自定义的模型路径（某些节点 README 会单独指定）

Desktop 用户默认包含并启用 Manager；当前 Portable / Manual 版本把新版 Manager 集成在 ComfyUI core 中，但需要先安装 manager_requirements.txt，再用 --enable-manager 启动。如果 Manager 列表里找不到某个节点，可能是该节点未收录到 Registry，或网络失败导致列表只显示缓存或本地信息——此时需要去原项目仓库核对。

判断顺序：先看终端是否有 Import failed → 再看 Manager / Registry 是否有这个节点 → 再看模型路径。workflow 复现的完整步骤（包括导入后如何补齐模型和连接节点）见 ComfyUI Workflow 复用指南。

2. 终端 Import failed 怎么读？

终端出现 Import failed 时，报错最后一段通常会给出具体 missing module 或版本冲突。根据报错类型判断下一步：

判断逻辑：

1. ModuleNotFoundError: No module named 'xxx' → 缺少 Python 包

   • 不要用系统级 pip install，必须装到 ComfyUI 自己的 Python 环境
   • Portable 用户命令：python_embeded\python.exe -m pip install -r custom_nodes\xxx\requirements.txt
   • Desktop / Manual 用户路径不同，需要先定位 ComfyUI 使用的 Python 路径

2. torch / CUDA / cuDNN 相关报错 → PyTorch 版本或 GPU 后端不匹配

   • 检查 PyTorch 版本：python -c "import torch; print(torch.__version__)"
   • 检查 GPU driver 是否符合当前官方系统要求
   • 某些节点要求特定 torch 版本，与 ComfyUI 已装版本冲突时需要权衡

3. custom node 自身代码报错 → 该节点版本问题或代码缺陷

   • 去该节点的 GitHub issue 搜索相同报错
   • 如果是新版本导致，尝试回退到旧 commit

易变事实提醒：截至本文打包时，官方推荐 Python 3.13，3.12 是部分 custom node dependencies 在 3.13 出问题时的 fallback。PyTorch / CUDA 版本更新快，以当前官方系统要求为准。

3. Manager 装完仍缺 / 依赖冲突怎么办？

Manager 显示已安装，重启后仍然红，或终端出现 torch / torchvision 版本冲突，通常有几种原因：

Manager 装完仍缺的可能原因：

• 网络失败，列表回退本地信息，实际未下载成功
• 该节点的 Python 依赖未装，需要手动 pip install -r requirements.txt
• 节点被禁用或没有被 ComfyUI 正常加载
• 该节点与当前 ComfyUI 版本不兼容，需要去 issue 查是否有人反馈

依赖冲突的可能原因：

• 不同 custom node 要求不同版本的 torch / torchvision / numpy
• 某个节点的 requirements.txt 锁定严格版本，与已装版本冲突

解决顺序：

1. 检查终端完整报错，按 Import failed 分诊处理
2. 尝试禁用或移除冲突节点，看 ComfyUI 是否恢复正常
3. 检查 requirements.txt 是否有严格版本锁定（如 torch==2.4.1）
4. 如果无法解决，向 custom node 作者报 issue，需提供：
   • 完整报错
   • python main.py --disable-all-custom-nodes 测试结果（问题是否消失）
   • Python / PyTorch / GPU driver 版本

易变事实提醒：Manager 正在经历新旧 UI、内置与 legacy 安装方式变化，按钮位置和文案以当前官方文档为准。OOM / 显存峰值导致卡住的分诊见 ComfyUI 低显存优化指南。

4. 模型路径与 dropdown 不出现

ComfyUI 安装本体不包含模型文件。checkpoint、VAE、LoRA、ControlNet、upscaler 等需要手动下载后放入 ComfyUI/models/ 对应子目录。

放入后 dropdown 不出现的检查顺序：

1. 文件是否放在正确目录

   • checkpoint 放在 ComfyUI/models/checkpoints/
   • VAE 放在 ComfyUI/models/vae/
   • LoRA、ControlNet、upscaler 放到相应类型目录
   • custom node 可能使用不同目录，应以该项目 README 为准

2. 是否需要重启或刷新

   • 放入文件后，重启 ComfyUI 或按当前界面支持的方式刷新节点定义

3. 文件是否损坏或不完整

   • 检查文件大小是否与下载页面一致
   • 尝试重新下载或验证文件完整性

4. loader node 是否支持该模型类型

   • 选择与模型类型匹配的 loader 和 workflow template
   • FLUX / SD3.x 等新架构可能需要特定 text encoder、VAE 和节点组合
   • custom node 的模型路径可能与通用 ComfyUI/models/ 指引不同，见该节点 README

5. extra_model_paths.yaml 配置

   • Portable / Manual 可用 extra_model_paths.yaml 引用外部模型库，保存后需要重启
   • Desktop 使用自己的 extra models config 文件，配置路径以当前官方文档为准

模型选型和 VAE 匹配规则见 Stable Diffusion 模型选型指南。

启动卡死诊断：—disable-all-custom-nodes 与二分法

ComfyUI 卡在 loading、白屏、无法进入 UI，或启动后前端空白，常见原因之一是 custom node frontend extension 冲突。官方提供的 --disable-all-custom-nodes 参数能快速判断问题是否来自 custom nodes。

1. —disable-all-custom-nodes 启动测试

命令：

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

Portable 用户操作：

复制 run_nvidia_gpu.bat 或 run_cpu.bat，在启动命令中加入 --disable-all-custom-nodes 后单独保存并运行。

判断逻辑：

• 如果禁用所有 custom nodes 后问题消失 → 问题来自 custom node
  • 继续用二分法定位具体节点
• 如果仍存在问题 → 问题不在 custom nodes
  • 转向 ComfyUI core、系统要求、GPU driver 和 Python / PyTorch 环境
  • 检查模型文件是否损坏或路径错误
  • 检查显存峰值是否导致卡住（见 ComfyUI 低显存优化指南）

易变事实提醒：启动参数名称和默认值以 python main.py --help 为准。

2. 二分法定位坏节点

如果 --disable-all-custom-nodes 测试确认问题来自 custom node，但不知道是哪一个，用二分法逐步定位。

原理：每次启用/禁用一半 custom nodes，观察问题是否出现，逐步缩小范围。

步骤：

1. 先备份 ComfyUI/custom_nodes/ 目录
2. 将一半节点文件夹临时移到测试目录
3. 启动 ComfyUI，观察问题是否出现
4. 判断：
   • 如果问题消失 → 坏节点在被移出的那一半中
   • 如果问题仍存在 → 坏节点在保留的那一半中
5. 重复以上步骤，逐步缩小范围，直到定位到具体节点

定位到节点后：

• 检查该节点的 GitHub issue，搜索相同报错
• 检查 requirements.txt 是否有严格版本锁定
• 尝试更新、替换、禁用或移除该节点
• 如果是新版本导致，尝试回退到旧 commit

向 custom node 作者报 issue 时需提供：

• ComfyUI 版本
• 完整报错和复现步骤
• 操作系统
• python main.py --disable-all-custom-nodes 测试结果
• Python / PyTorch / GPU driver 版本和硬件型号

VAE 输出异常：发灰、黑图、错配怎么排查？

VAE 输出发灰、发白、偏色、全黑，常见原因有 VAE 精度参数、错配 VAE、没接正确的 VAE loader、attention 精度问题，或新模型需要不同的文件与节点组合。按以下顺序排查。

1. VAE 发灰/黑图排查顺序

排查步骤：

1. 确认 workflow 是否正确连接 VAE

   • checkpoint loader 输出的 VAE 或独立 VAE loader 应连接到解码节点
   • 某些 checkpoint 内置 VAE；另一些模型需要单独下载并加载

2. 确认 VAE 文件是否匹配模型和工作流

   • SD1.5、SDXL、FLUX、SD3.x 需要的 VAE、text encoder 和 loader 组合可能不同
   • 先按模型的官方 workflow template 或项目 README 跑通最小工作流

3. 检查是否使用了 --fp16-vae 启动参数

   • 官方 Startup Flags 文档注明：--fp16-vae 可能导致 black images
   • 如果用了，尝试去掉或按硬件支持换成 --fp32-vae / --bf16-vae

4. 尝试精度参数

   • --fp32-vae：全精度 VAE，通常占用更多显存
   • --bf16-vae：BF16 精度，需要硬件和后端支持
   • --cpu-vae：在 CPU 上运行 VAE，通常更慢
   • --force-upcast-attention：可用于验证 attention upcast 是否修复黑图，不是通用画质开关

5. 最后检查显存 / 驱动 / 依赖

   • 显存峰值可能导致 VAE decode 失败
   • GPU driver 是否符合当前系统要求
   • PyTorch 与 GPU 后端是否匹配

常见错误症状：

症状	可能原因
发灰 / 发白 / 偏色	错 VAE、解码链路接错、工作流与模型不匹配
全黑	--fp16-vae、attention 精度、显存峰值或模型组合问题
报错或无法加载	VAE 文件损坏、路径错误、文件组合不完整

2. fp16 VAE 黑图风险与精度参数

很多教程推荐 --fp16-vae 来降低资源占用，但官方 Startup Flags 文档明确写着它可能导致 black images。这个参数不应脱离硬件、模型和日志单独套用。

VAE 精度参数对比：

参数	效果	适用场景
--fp16-vae	VAE 用 FP16 计算，通常降低资源占用	可能导致黑图，谨慎使用
--fp32-vae	VAE 用全精度计算	黑图排查时可测试，通常更占显存
--bf16-vae	VAE 用 BF16 计算	需硬件和后端支持
--cpu-vae	VAE 在 CPU 上计算	显存紧张时可测试，通常更慢

Attention 精度参数：

• --force-upcast-attention：用于验证 attention upcast 是否修复黑图
• --dont-upcast-attention：与 --force-upcast-attention 互斥，仅用于调试

使用建议：

• 不要盲目追教程推荐的“加速参数”，先看症状和终端日志
• 出现黑图后，先去掉 --fp16-vae，再按环境测试 --fp32-vae 或 --force-upcast-attention
• 参数名称、默认值、适用硬件随版本变化，以当前 python main.py --help 为准
• 低显存 / OOM 参数完整表见 ComfyUI 低显存优化指南

3. 错 VAE / 错模型分诊

同一个 workflow 换模型或 VAE 后输出异常，往往是模型、VAE、loader 或工作流模板不匹配。不同模型需要的文件与节点组合不同，不能直接复用旧架构的经验。

不同模型的检查重点：

模型类型	VAE 检查	loader / workflow 检查
SD1.5 checkpoint	使用模型内置或匹配的 SD1.5 VAE	使用与 SD1.5 对应的基础 workflow
SDXL checkpoint	使用模型内置或匹配的 SDXL VAE	使用与 SDXL 对应的 template 和 loader
FLUX / SD3.x	按模型 README 准备 VAE 与 text encoder	按官方 template 或项目文档组合节点

判断方式：

1. 检查模型 README、项目页或官方 template
   • 确认是否内置 VAE、推荐哪些 companion weights、需要哪些 loader
2. 检查 loader 中选择的文件
   • dropdown 选中的 VAE 是否与当前模型和工作流匹配
3. 从最小官方模板开始验证
   • 先排除自定义后处理和复杂节点，再逐个接回原 workflow

常见症状与原因：

症状	原因
发灰 / 发白 / 偏色	VAE、模型或解码链路错配
报错或无法加载	VAE 文件损坏、路径错误、文件组合不完整
简化 workflow 正常、原 workflow 异常	后处理或 custom node 改变了解码链路

模型选型和 VAE 匹配详细规则见 Stable Diffusion 模型选型指南。

更新维护策略：stable/development、备份、回退

ComfyUI 更新后原来能跑的工作流崩了，是常见维护问题。Development 版本包含最新 commit，但可能有潜在问题；Stable 版本通常更稳，也可能晚一些拿到新功能。更新前备份、记录版本、知道怎么回退，比连续点完所有更新更重要。

1. 更新前备份 + stable/development 选择

更新前备份清单：

1. 记录当前 ComfyUI commit hash

   • Git 用户：git rev-parse HEAD
   • Portable / Desktop：记录当前版本和更新通道

2. 记录 Python / PyTorch 版本

   • Python：python --version
   • PyTorch：python -c "import torch; print(torch.__version__)"
   • NVIDIA 环境可用 nvidia-smi 记录 driver 版本

3. 记录常用 custom node 版本

   • 导出或保存 Manager 中的节点清单
   • 记录关键节点仓库的 commit hash

4. 备份 workflow 和配置

   • 将常用 workflow JSON 导出到单独目录
   • 备份 extra_model_paths.yaml、Desktop extra models config 和重要 user data

Stable vs Development：

版本类型	特点	适用场景
Stable / Release	经过稳定化的 release，功能可能滞后	生产环境、长期维护
Development / Latest	最新 commit，较快获得新功能	测试新模型、新功能和节点兼容性
指定 commit	固定在一个已知版本，不自动获得后续修复	临时回退、回归定位和复现实验

不同安装方式的更新策略：

安装方式	更新策略
Desktop	默认稳定通道，也可在当前管理界面选择更新通道
Portable	update_comfyui_stable.bat 追 stable，update_comfyui.bat 追 development
Manual Git	git pull 后在 ComfyUI 环境中更新 requirements.txt；可切换 commit 回退

易变事实提醒：脚本名称和 Desktop 设置以当前官方 Update ComfyUI 文档为准。

2. 更新后崩了怎么回滚

更新后 ComfyUI 或 custom nodes 失效，需要先判断问题来源，再选择回滚方式。

判断问题来源：

1. 如果只更新了 ComfyUI core

   • 用 --disable-all-custom-nodes 检查 core 是否能启动
   • 检查 custom nodes 是否需要同步更新

2. 如果只更新了某个 custom node

   • 尝试回退该节点到旧版本
   • 或禁用该节点，看 ComfyUI 是否恢复正常

3. 如果更新了依赖

   • 重新检查 Python、PyTorch 和关键包版本
   • Portable 的 update_comfyui_and_python_dependencies.bat 会重装全部依赖，官方明确提醒它可能造成依赖冲突并破坏依赖特定版本的 custom nodes

Git 回滚：

# 查看历史 commit
git log --oneline

# 切换到已知可用的 commit
git checkout <commit-hash>

# 仅在对应 ComfyUI 环境中按该版本需要更新依赖
pip install -r requirements.txt

Portable 和 Desktop 的回退入口会随版本变化；优先恢复更新前备份，并按当前官方更新文档操作。不要把卸载重装当第一步，因为它会丢掉定位问题所需的版本和配置现场。

向 custom node 作者报 issue 时需提供：

• 完整报错和复现步骤
• ComfyUI、Python、PyTorch 和 GPU driver 版本
• python main.py --disable-all-custom-nodes 测试结果
• 更新前后 core 或节点版本对比

下一步与延伸阅读

排障后需要深入其他主题，可以沿 ComfyUI 系列继续处理：

1. Workflow 复现完整步骤

   • 导入 workflow 后如何补齐节点和模型、如何连接 loader
   • 见 ComfyUI Workflow 复用指南

2. 低显存加速参数

   • OOM / 显存峰值导致卡住时，继续检查 --lowvram、VAE 和模型量化
   • 见 ComfyUI 低显存优化指南

3. 放大与 Inpaint 实战

   • FaceDetailer、Impact Pack 等后处理节点缺失或更新冲突后的工作流处理
   • 见 ComfyUI 放大与 Inpaint 实战

4. 视频生成实战

   • 视频工作流、VAE 与导出最后一步问题
   • 见 ComfyUI 视频生成实战

5. API 批量自动化

   • API format、/prompt、node_errors、队列管理
   • 见 ComfyUI API 批量出图自动化

6. 模型选型与 VAE 匹配

   • checkpoint、VAE、LoRA 选型和不同模型的 loader 配置
   • 见 Stable Diffusion 模型选型指南