排错总览：出问题先看这页（60 秒速检）

ComfyUI 报错时，先别急着搜报错原文。大多数 ComfyUI 报错都能在 60 秒内归到四类：环境与启动、模型加载、显存与生成、自定义节点。这页帮你先做一次快速体检，把问题定位到类别，再跳到对应专页深入处理。

学完你能做什么

• 用 3 条命令在 60 秒内确认 GPU、CUDA 和 Python 环境是否正常
• 把报错按「环境 / 模型 / 显存 / 节点」归类，不再盲目搜索
• 对照高频报错原文，直接套用已验证的解决方案
• 知道自己解决不了时，该收集哪些信息、去哪里提问

首次排查：60 秒速检

出问题的第一件事：回到启动 ComfyUI 的终端窗口读日志。生成失败时界面会弹出「Prompt execution failed」对话框，点「Show report」能看到详细错误信息——先把它复制下来。

然后在终端跑这三条命令做环境体检：

# 1. 确认 GPU 能被系统识别（NVIDIA 显卡）
nvidia-smi

# 2. 确认 PyTorch 的 CUDA 可用
python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

# 3. 确认 Python 版本（需 3.9+，推荐 3.12）
python --version

你应该看到：第 1 条列出显卡型号和驱动版本；第 2 条输出 CUDA available: True；第 3 条输出 3.9 以上的版本号。任何一条不符合预期，先跳到装不上怎么办：安装与启动排错。

💡 先排除自定义节点

官方收到的反馈 issue 中，大多数与自定义节点有关。深入排查前，先按自定义节点排错：先禁用再二分的方法禁用全部自定义节点，确认问题是否由节点引起。

常见问题排查

环境与启动相关 ComfyUI 报错

"Torch not compiled with CUDA enabled"

原因：安装的 PyTorch 是 CPU 版本，没有编译 CUDA 支持，GPU 无法参与计算。

解决：

1. 先卸载现有 torch：

pip uninstall torch

2. 重装 CUDA 版 PyTorch（CUDA 13.0）：

pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

3. 验证安装：

python -c "import torch; print(torch.cuda.is_available())"

你应该看到：输出 True。

"Frontend or Templates Package Not Updated"

原因：通过 Git 更新 ComfyUI 后，前端依赖没有同步更新。

解决：

pip install -r requirements.txt

你应该看到：依赖安装完成后重启 ComfyUI，提示消失。

模型加载相关问题

"Value not in list: ckpt_name: 'model-name.safetensors' not in []"

原因：工作流引用的模型文件不存在——要么没下载，要么放错了子目录。not in [] 中的空列表说明 ComfyUI 在对应目录里一个模型都没找到。

解决：

1. 核对模型是否放在正确的子目录：
   • Checkpoints：models/checkpoints/
   • VAE：models/vae/
   • LoRA：models/loras/
   • ControlNet：models/controlnet/
2. 缺模型就用 ComfyUI Manager 自动下载，或手动下载后放入对应目录。
3. 如果模型放在其他位置（比如和其他绘图软件共用），编辑 extra_model_paths.yaml 添加自定义模型目录，参考Windows 便携包安装。

你应该看到：重启 ComfyUI 后，节点下拉框里能选到该模型。

"Error while deserializing header"

原因：模型文件在下载时损坏，或磁盘空间不足、文件权限不对导致无法读取。

解决：

1. 重新下载模型（模型文件可能有 2–15GB 以上，确保下载完整）。
2. 检查磁盘剩余空间是否足够。
3. 检查 ComfyUI 进程对模型文件有读取权限。
4. 换一个模型测试，确认是单个文件的问题还是系统性的问题。

显存与生成相关 ComfyUI 报错

"RuntimeError: CUDA out of memory"

原因：显存不够容纳当前模型和工作流，常见于大模型或高分辨率生成。

解决：按顺序逐步降低显存占用，每次改完重启 ComfyUI：

# 方案 1：先用 lowvram（文本编码器放到 CPU）
python main.py --lowvram

# 方案 2：不够再换 novram
python main.py --novram

# 方案 3：最后手段，纯 CPU（很慢，仅绝对必要时使用）
python main.py --cpu

同时可以降低生成分辨率或批量大小、关掉其他占用显存的程序。更多系统解法见显存不足与卡顿：OOM 的系统解法。

你应该看到：生成能跑完，不再中断报错。

"生成结果全黑或纯色"

原因：输出环节出了问题。有据可查的成因包括：VAE 环节异常（默认文生图管线是 KSampler → VAE Decode → Save Image，VAE 加载不对会直接影响输出）；--fp16-vae 启动参数以 fp16 运行 VAE，可能导致黑图；量化模型上注意力后端可能静默返回黑色输出。

解决：

1. 检查工作流：确认 KSampler 之后接的是 VAE Decode，且加载的 VAE 与模型架构匹配（例如 Flux 要用 ae.safetensors，不能用 sdxl_vae 或 taesd）。
2. 如果启动时加了 --fp16-vae，去掉该参数重启。
3. 如果启用了 FlashAttention（--use-flash-attention 或节点包开启），改用默认注意力后端重启再试——在量化模型上禁用 FlashAttention 已被验证能解决全黑输出。
4. 关闭实时预览排除干扰：某些情况下只有预览是黑的，保存的文件其实正常。

你应该看到：重新生成后输出正常图像。

自定义节点相关问题

"Can't Find Custom Node"（找不到自定义节点）

原因：工作流用到的自定义节点未安装或未正确启用，前端校验报错。

解决：

1. 先在 ComfyUI 设置中临时禁用节点校验，确认问题范围。
2. 按提示补装对应节点包并重启。
3. 若问题持续，按自定义节点排错：先禁用再二分的流程禁用全部节点后二分定位。

"Missing nodes still showing as missing after installation and restart"

原因：节点包装了但依赖导入失败——控制台/日志里常见「Failed to import」。典型成因：节点包需要额外的 wheel 依赖；不同插件对依赖版本要求冲突（如一个要 torch==2.4.1、另一个要 torch>=2.4.2）；网络问题导致依赖没装上。

解决：

1. 打开终端日志，找到「Failed to import」对应的节点包名。
2. 手动安装该节点包缺失的依赖。
3. 依赖版本冲突时，参考自定义节点排错页的 Python 环境管理方法处理。

还是不行？

收集好这些信息再去提问，能大幅提高解决效率：

# GPU 型号与驱动版本
nvidia-smi --query-gpu=driver_version --format=csv

# CUDA 是否可用及版本
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"

# Python 版本
python --version

提问时附上：完整报错原文（终端日志或「Show report」内容）、GPU 型号、ComfyUI 版本、安装方式（桌面版 / 便携版 / 手动安装）、是否使用自定义节点。

去哪里问：

• 自定义节点问题：先走自定义节点排错：先禁用再二分
• 安装与启动问题：装不上怎么办：安装与启动排错
• 向官方报 bug：确认不是自定义节点引起后，带上上述信息提交 GitHub issue

下一课预告

这页帮你把 ComfyUI 报错归到四大类。下一课深入最高频的一类：自定义节点排错：先禁用再二分，教你用二分法快速锁定肇事节点。