ComfyUI 启动失败、节点缺失、模型不显示怎么办？完整排障教程

ComfyUI 启动失败、节点缺失、模型不显示怎么办？

本文系统梳理 ComfyUI 启动失败、节点缺失、模型不显示的常见原因与解决方法，覆盖启动日志、Python 依赖、CUDA/Torch、ComfyUI-Manager、自定义节点目录、模型路径、extra_model_paths.yaml、更新回退和安全使用建议，适合 Stable Diffusion 本地绘图用户收藏。

ComfyUI 启动失败、节点缺失、模型不显示怎么办？

★ 导读：ComfyUI 启动失败、节点缺失、模型不显示，通常不是“工具坏了”，而是环境、依赖、自定义节点、模型路径或版本兼容出现问题。本文按“看日志 – 定位类型 – 单项修复 – 再验证”的方法，整理一套适合新手照做的排障流程。

一、问题概览：ComfyUI 常见故障分为三大类

ComfyUI 是节点式 Stable Diffusion/图像生成工作流工具，灵活度高，但也意味着安装环境、模型文件、自定义节点、Python 依赖和显卡驱动之间更容易出现兼容问题。遇到异常时，先确认属于哪一类，再处理会更高效。

1.1 启动失败：界面打不开或终端报错

双击 run_nvidia_gpu.bat / run_cpu.bat 后窗口闪退，浏览器无法访问 127.0.0.1:8188。
终端报错 Python、Torch、CUDA、xformers、依赖包缺失或端口占用。
显卡驱动、CUDA、PyTorch 版本不匹配，导致 GPU 无法启用或只能用 CPU 运行。

1.2 节点缺失：导入工作流后出现红色 Missing Nodes

下载别人工作流后，画布出现红色节点，提示某些 custom nodes 未安装。
安装节点后仍不显示，可能是目录层级错误、依赖没有装到 ComfyUI 环境，或版本不兼容。
多个自定义节点之间发生冲突，导致启动慢、节点加载失败或页面报错。

1.3 模型不显示：文件放进去了但加载器找不到

checkpoint、LoRA、VAE、ControlNet、Upscaler 放错目录或目录名拼写不一致。
模型文件没下载完整、格式不兼容、扩展名错误，或名称中包含特殊字符导致识别异常。
使用共享模型目录时，extra_model_paths.yaml 没配置好，ComfyUI 没有扫描到外部路径。

二、排障总流程：先看日志，不要盲目重装

2.1 新手最容易犯的三个错误

一遇到报错就删除重装，导致原有模型、工作流、节点配置丢失。
同时更新 ComfyUI、Python、PyTorch、节点、模型，结果无法判断是哪一步出错。
把节点依赖安装到系统 Python，而不是当前 ComfyUI 的 Python 环境。

2.2 正确排查顺序

第一步：重新启动 ComfyUI，复制终端完整报错，不要只看最后一行。
第二步：判断报错关键词，常见包括 ModuleNotFoundError、CUDA、torch、port、missing node、model not found。
第三步：如果近期安装过新节点，先禁用或移走新节点，确认是否恢复。
第四步：如果是模型问题，核对模型类型、文件夹、文件完整性和加载节点。
第五步：只修一个变量，重启验证，再进行下一项修改。

★ 核心原则：ComfyUI 排障不是越快重装越好，而是要保留现场：报错截图、终端日志、安装方式、最近更新过的节点、模型路径和 Python 环境。

三、ComfyUI 启动失败怎么办？

启动失败时，先不要急着安装新节点或下载新模型。最重要的是确认 ComfyUI 是否真正启动、端口是否占用、Python 依赖是否完整、Torch 是否能识别 GPU。

3.1 浏览器打不开 127.0.0.1:8188

确认终端窗口是否还在运行。如果窗口闪退，说明启动脚本执行失败，需要从命令行运行以查看错误。
检查端口是否被占用。默认端口通常是 8188，如果冲突，可换端口启动。
确认防火墙或安全软件没有拦截本地服务。
如果使用远程服务器，需要确认监听地址、端口映射和防火墙放行。

常见启动检查：
# Windows Portable 通常使用
run_nvidia_gpu.bat

# 手动安装可进入目录后运行
python main.py

# 如果 8188 端口冲突，可尝试指定端口
python main.py –port 8189

3.2 Python / 依赖缺失报错

如果出现 ModuleNotFoundError，通常是依赖包缺失，优先在 ComfyUI 当前环境中执行 pip install -r requirements.txt。
Windows Portable 不要直接用系统 python 安装依赖，要使用 python_embeded\python.exe。
手动安装用户需要先激活虚拟环境，再安装依赖，避免污染系统 Python。

Windows Portable 安装依赖示例：
python_embeded\python.exe -m pip install -r ComfyUI\requirements.txt

自定义节点依赖示例：
python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\节点目录\requirements.txt

3.3 CUDA / 显卡 / Torch 问题

如果提示 Torch not compiled with CUDA enabled，说明当前 PyTorch 不是 CUDA 版本或显卡环境不匹配。
Windows Desktop 官方故障排查中提示，Windows Desktop 版本仅支持 NVIDIA CUDA GPU；其他显卡或特殊环境可考虑 Portable 或手动安装。
显存不足时，尝试降低分辨率、减少 batch、关闭高占用节点，或使用低显存启动参数。

★ 不要乱装 CUDA：很多问题不是“缺 CUDA”，而是 PyTorch、显卡驱动、Python 环境、ComfyUI 版本之间不匹配。没有把握时，优先使用官方推荐安装包或 Portable 版本。

四、节点缺失怎么办？自定义节点排查与修复

4.1 使用 ComfyUI-Manager 安装缺失节点

导入工作流后，先查看 Missing Nodes 列表，记录节点名或节点包名。
如果安装了 ComfyUI-Manager，可使用 Install Missing Custom Nodes 或 Custom Nodes Manager 搜索安装。
安装完成后必须重启 ComfyUI，很多节点不会热加载。
如果 Manager 找不到节点，尝试去工作流作者页面查看依赖清单，或在 GitHub 搜索节点名称。

4.2 手动安装节点时检查目录层级

官方 Manager 故障排查文档强调，ComfyUI-Manager 文件必须位于 ComfyUI/custom_nodes/comfyui-manager。自定义节点也类似，最常见问题是下载 ZIP 后多了一层目录，或者把节点文件直接散放在 custom_nodes 根目录。

正确示例：
ComfyUI/custom_nodes/ComfyUI-Manager/__init__.py
ComfyUI/custom_nodes/ComfyUI-Custom-Scripts/__init__.py

常见错误：
ComfyUI/custom_nodes/ComfyUI-Manager-main/ComfyUI-Manager/__init__.py
ComfyUI/custom_nodes/__init__.py # 把节点文件直接放根目录

4.3 安装依赖到正确环境

每个 custom node 可能有自己的 requirements.txt，必须装到当前 ComfyUI 环境。
Portable 用户使用 python_embeded\python.exe，手动安装用户要先进入虚拟环境。
如果依赖版本冲突，不要立刻全量更新，可先禁用新节点验证。

4.4 用二分法定位冲突节点

ComfyUI 官方自定义节点问题排查文档推荐用二分法：一次启用或禁用一半节点，观察问题是否复现，逐步缩小到具体冲突节点。这个方法比逐个猜测更快。

把 custom_nodes 中一半第三方节点临时移到备份文件夹，重启测试。
如果问题消失，说明冲突在被移走的一半；如果仍存在，继续检查留下的一半。
重复分组，直到定位到具体节点或具体依赖。
定位后再决定更新、降级、删除或等待作者修复。

五、模型不显示怎么办？路径、格式和扫描逻辑

5.1 先确认模型类型

Checkpoint 是基础模型，通常放在 models/checkpoints。
LoRA 是风格/人物/产品微调权重，通常放在 models/loras。
VAE 放在 models/vae，ControlNet 放在 models/controlnet，Embeddings 放在 models/embeddings。
不要把所有 .safetensors 文件都放到 checkpoints，文件扩展名相同不代表模型类型相同。

5.2 检查模型文件是否完整

下载中断的模型可能只有几 KB 或几十 MB，而正常 checkpoint 通常较大。
优先使用 .safetensors 格式，避免来源不明的模型文件。
模型名称尽量使用英文、数字、下划线，避免特殊符号和过长路径。
如果刚放入模型后不显示，刷新模型列表或重启 ComfyUI。

5.3 使用 extra_model_paths.yaml 共享模型目录

如果你同时使用 Stable Diffusion WebUI、Forge、ComfyUI，可以通过 extra_model_paths.yaml 让 ComfyUI 扫描外部模型目录，避免重复占用磁盘空间。

extra_model_paths.yaml 示例：
my_models:
base_path: D:/AIModels
checkpoints: checkpoints
vae: vae
loras: loras
controlnet: controlnet
embeddings: embeddings

★ 路径建议：模型路径尽量不要放在系统盘深层目录，也不要频繁移动。使用共享目录前，先备份 extra_model_paths.yaml，避免配置错误导致所有模型都不显示。

六、更新后坏了怎么办？更新策略与回退思路

ComfyUI 更新很频繁，节点生态也变化很快。官方更新文档提醒，update_comfyui_and_python_dependencies.bat 会更新 ComfyUI、PyTorch 并重新安装全部 Python 依赖，可能引发依赖冲突或影响自定义节点。

6.1 更新前要备份什么

ComfyUI/user/default/workflows 或你保存工作流的文件夹。
ComfyUI/custom_nodes 目录，尤其是已经能稳定运行的节点版本。
extra_model_paths.yaml、自定义启动脚本、配置文件。
重要模型文件的下载来源、版本和触发词说明。

6.2 更新顺序建议

先更新 ComfyUI 核心，确认能正常启动。
再更新少量高频节点，逐个验证重要工作流。
最后再考虑更新 PyTorch、CUDA 相关依赖。
如果你正在做稳定项目，不建议在交付前一天大规模更新。

6.3 出错后的回退思路

回忆最近修改：新增节点、更新节点、换模型、改配置、升级显卡驱动。
恢复备份 custom_nodes，或先把新安装节点移出目录。
如果是模型不显示，恢复 extra_model_paths.yaml 或检查模型目录。
如果依赖冲突严重，考虑新建一份干净 ComfyUI，再逐步迁移模型和节点。

七、稳定使用 ComfyUI 的推荐工作流

7.1 新手不要一开始就堆复杂工作流

先跑官方基础工作流：Checkpoint + Prompt + Sampler + VAE Decode + Save Image。
确认基础出图稳定后，再添加 LoRA、ControlNet、IP-Adapter、Upscale、AnimateDiff 等模块。
每加入一个新节点，就保存一个工作流版本，方便回退。
遇到报错时，把复杂工作流简化到最小可复现版本。

7.2 实用命名与文件管理

模型文件命名包含模型名、版本、用途，例如 realistic_v6_checkpoint.safetensors。
工作流文件按项目、功能、日期命名，例如 product_photo_upscale_2026-05.json。
把常用提示词、模型触发词、节点版本写进项目说明。
定期清理未使用模型，防止模型过多导致选择混乱。

7.3 安全与合规建议

只从可信来源下载模型和节点，避免运行不明脚本。
商业项目使用模型前，确认模型作者的授权范围和商用限制。
避免生成侵权、仿冒、违法或伤害性内容。
不要把客户隐私照片、证件、内部资料上传到不可信模型或工作流中。

八、常见问题 FAQ

Q1：ComfyUI 打不开网页怎么办？

先看终端是否正常运行。如果终端已经闪退，说明启动失败；如果终端运行但浏览器打不开，检查 8188 端口、防火墙、代理和访问地址。

Q2：节点安装了还是显示缺失怎么办？

检查目录层级是否正确，依赖是否装到 ComfyUI 环境，安装后是否重启。如果仍然缺失，可能是节点包名和工作流里的节点名不一致，需要根据工作流说明手动安装。

Q3：为什么模型放进去了但找不到？

通常是放错目录、模型类型判断错误、文件没下载完整、文件名异常或 extra_model_paths.yaml 配置错误。先用官方模型目录结构逐项核对。

Q4：要不要使用 ComfyUI-Manager？

建议新手使用。它能帮助安装自定义节点、管理模型和修复部分缺失节点。但仍要注意来源安全，不要随意安装未知节点。

Q5：更新后节点全坏了怎么办？

先停用最近更新或新增的节点，查看日志定位冲突。必要时恢复备份 custom_nodes，或新建干净 ComfyUI，再逐步迁移。

Q6：ComfyUI 是否必须 NVIDIA 显卡？

不一定，但不同安装方式支持情况不同。官方故障排查提示 Windows Desktop 版本仅支持 NVIDIA CUDA GPU；其他设备可考虑 Portable、手动安装或 CPU/Apple Silicon 等对应方案。

九、总结：ComfyUI 排障的核心是“最小化变量”

ComfyUI 启动失败、节点缺失、模型不显示，大多能通过日志、路径、依赖和版本四个方向定位。新手最稳的做法是：先跑通基础环境，再装节点；先确认模型目录，再导入复杂工作流；先单项修复，再批量更新。只要建立好备份和版本管理习惯，ComfyUI 就能从“经常报错的工具”变成稳定的本地 AI 绘图工作台。

★ 发布建议：这篇文章适合放在“热门 AI 工具问题排查教程”或“Stable Diffusion / ComfyUI 本地部署教程”栏目，建议搭配封面图、流程图、目录和 FAQ，提高搜索点击率与停留时长。

参考资料

ComfyUI 官方故障排查概览：https://docs.comfy.org/troubleshooting/overview
ComfyUI 自定义节点问题排查：https://docs.comfy.org/troubleshooting/custom-node-issues
ComfyUI 模型问题排查：https://docs.comfy.org/troubleshooting/model-issues
ComfyUI 模型核心概念：https://docs.comfy.org/development/core-concepts/models
ComfyUI 安装自定义节点：https://docs.comfy.org/installation/install_custom_node
ComfyUI-Manager 安装：https://docs.comfy.org/manager/install
ComfyUI-Manager 故障排查：https://docs.comfy.org/manager/troubleshooting
ComfyUI 更新说明：https://docs.comfy.org/installation/update_comfyui
ComfyUI Windows Desktop 安装说明：https://docs.comfy.org/installation/desktop/windows
ComfyUI Portable Windows 安装说明：https://docs.comfy.org/installation/comfyui_portable_windows