如何排查和解决 ComfyUI 中出现的错误

我们日常收到的诸多反馈问题，我们发现绝大部分的问题提交都与自定义节点有关,所以在提交对应的错误反馈之前，请你确保详细阅读了自定义节点故障排除部分的指南，来确保对应的问题并不是由 ComfyUI 核心问题导致的。

自定义节点故障排除指南

查看如何排查自定义节点导致的问题。

常见问题与快速修复

在深入详细故障排除之前，请尝试这些常见解决方案：

ComfyUI 无法启动

症状： 应用程序在启动时崩溃、黑屏或无法加载

快速修复：

检查系统要求 - 确保您的系统符合最低要求
更新 GPU 驱动程序 - 从 NVIDIA/AMD/Intel 下载最新驱动程序

生成失败或产生错误

症状： “Prompt execution failed”（提示执行失败）对话框，带有”Show report”（显示报告）按钮，工作流停止执行

快速修复：

点击”Show report” - 阅读详细错误消息以识别具体问题
检查是否是自定义节点问题 - 遵循我们的自定义节点故障排除指南
验证模型文件 - 查看模型文档了解模型设置
检查显存使用情况 - 关闭其他使用 GPU 内存的应用程序

性能缓慢

症状： 生成时间非常慢、系统冻结、内存不足错误

快速修复：

降低分辨率/批次大小 - 减少图像大小或图像数量
使用内存优化标志 - 请参见下方性能优化部分
关闭不必要的应用程序 - 释放 RAM 和显存
检查 CPU/GPU 使用率 - 使用任务管理器识别瓶颈

性能优化命令：

对于低显存系统：

# 低显存模式（将模型分成多个部分）
python main.py --lowvram

# 当 --lowvram 不够用时的更低显存模式
python main.py --novram

# CPU 模式（非常慢但适用于任何硬件）
python main.py --cpu

提高性能：

# 禁用预览（节省显存和处理）
python main.py --preview-method none

# 将模型保持在显存中（更快但使用更多显存）
python main.py --highvram

# 强制 FP16 精度（更快，使用更少显存）
python main.py --force-fp16

# 使用优化的注意力机制
python main.py --use-pytorch-cross-attention
python main.py --use-flash-attention

# 异步权重卸载
python main.py --async-offload

内存管理：

# 为操作系统保留特定显存量（以 GB 为单位）
python main.py --reserve-vram 2

# 禁用智能内存管理
python main.py --disable-smart-memory

# 使用不同的缓存策略
python main.py --cache-none  # 更少的内存使用
python main.py --cache-lru 10  # 缓存 10 个结果

安装过程中出现的问题

桌面应用问题

有关全面的桌面安装故障排除，请参见桌面安装指南。

无法安装：以管理员身份运行安装程序
缺少依赖项：安装 Visual C++ 可再发行组件
启动时崩溃：检查 Windows 事件查看器以获取错误详细信息

手动安装问题

文档可能略有过时。如果出现问题，请手动验证是否存在更新的稳定版本的 pytorch 或任何列出的库。请参考 pytorch 安装矩阵或 ROCm 网站等资源。

Python 版本冲突：

# 检查 Python 版本（需要 3.9+，推荐 3.12）
python --version

# 使用虚拟环境（推荐）
python -m venv comfyui_env
source comfyui_env/bin/activate  # Linux/Mac
comfyui_env\Scripts\activate     # Windows

包安装失败：

# 首先更新 pip
python -m pip install --upgrade pip

# 安装依赖项
pip install -r requirements.txt

# 对于 NVIDIA GPU（CUDA 12.8）
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu128

# 对于 AMD GPU（仅限 Linux - ROCm 6.3）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.3

Linux 特定问题

LD_LIBRARY_PATH 错误：

常见错误：

“libcuda.so.1: cannot open shared object file”
“libnccl.so: cannot open shared object file”
“ImportError: libnvinfer.so.X: cannot open shared object file”

解决方案：

现代 PyTorch 安装（最常见）：

# 对于带有 NVIDIA 包的虚拟环境
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 对于 conda 环境
export LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python3.12/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 或自动查找您的 Python site-packages
PYTHON_PATH=$(python -c "import site; print(site.getsitepackages()[0])")
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 您可能还需要其他 NVIDIA 库
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cuda_runtime/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$PYTHON_PATH/nvidia/cublas/lib:$LD_LIBRARY_PATH

查找你拥有的库：

# 检查已安装的 NVIDIA 包
python -c "import site; import os; nvidia_path=os.path.join(site.getsitepackages()[0], 'nvidia'); print('NVIDIA libs:', [d for d in os.listdir(nvidia_path) if os.path.isdir(os.path.join(nvidia_path, d))] if os.path.exists(nvidia_path) else 'Not found')"

# 查找 PyTorch 需要的缺失库
python -c "import torch; print(torch.__file__)"
ldd $(python -c "import torch; print(torch.__file__.replace('__init__.py', 'lib/libtorch_cuda.so'))")

为你的环境永久设置：

# 对于虚拟环境，添加到激活脚本
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> $VIRTUAL_ENV/bin/activate

# 对于 conda 环境
conda env config vars set LD_LIBRARY_PATH=$CONDA_PREFIX/lib/python*/site-packages/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH

# 对于全局 bashrc（根据需要调整 Python 版本）
echo 'export LD_LIBRARY_PATH=$(python -c "import site; print(site.getsitepackages()[0])")/nvidia/nvjitlink/lib:$LD_LIBRARY_PATH' >> ~/.bashrc

替代方案：使用 ldconfig：

# 检查当前库缓存
ldconfig -p | grep cuda
ldconfig -p | grep nccl

# 如果缺失，添加库路径（需要 root 权限）
sudo echo "/usr/local/cuda/lib64" > /etc/ld.so.conf.d/cuda.conf
sudo ldconfig

调试库加载：

# 详细库加载以查看缺失的内容
LD_DEBUG=libs python main.py 2>&1 | grep "looking for"

# 检查 PyTorch CUDA 可用性
python -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('CUDA version:', torch.version.cuda)"

模型相关问题

有关综合模型故障排除，包括架构不匹配、缺少模型和加载错误，请参见专门的模型问题页面。

网络和 API 问题

API 节点不工作

症状： API 调用失败、超时错误、配额超出

解决方案：

检查 API 密钥有效性 - 在用户设置中验证密钥
检查账户积分 - 确保有足够的 API 积分
验证互联网连接 - 使用其他在线服务进行测试
检查服务状态 - 提供商可能正在经历停机

连接问题

症状： “无法连接到服务器”、超时错误

解决方案：

检查防火墙设置 - 允许 ComfyUI 通过防火墙
尝试不同端口 - 默认是 8188，尝试 8189 或 8190
临时禁用 VPN - VPN 可能阻止连接
检查代理设置 - 如果不需要，禁用代理

硬件特定问题

NVIDIA GPU 问题

CUDA 错误、GPU 未检测到：

# 检查 CUDA 安装
nvidia-smi

# 验证 PyTorch CUDA 支持
python -c "import torch; print(torch.cuda.is_available())"

# 重新安装带 CUDA 的 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

AMD GPU 问题

ROCm 支持、性能问题：

# 安装 ROCm 版本的 PyTorch
pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm5.7

Apple Silicon (M1/M2/M3) 问题

MPS 后端错误：

# 检查 MPS 可用性
python -c "import torch; print(torch.backends.mps.is_available())"

# 如果 MPS 导致问题，强制使用 CPU
python main.py --force-fp16 --cpu

获取帮助和报告错误

报告错误之前

检查是否是已知问题：
- 搜索 GitHub Issues
- 检查 ComfyUI 论坛
- 查看 Discord 讨论
尝试基本故障排除：
- 使用默认工作流进行测试
- 禁用所有自定义节点（参见自定义节点故障排除）
- 检查控制台/终端中的错误消息

如何有效报告错误

对于 ComfyUI 核心问题

问题提交： GitHub Issues

对于桌面应用问题

问题提交： 桌面 GitHub Issues

对于前端问题

问题提交： 前端 GitHub Issues

对于自定义节点问题

问题提交： 请到对应的自定义节点仓库中提交问题

在 issue 中你需要提供的信息

报告任何问题时，请包括以下内容：

系统信息

操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等）
ComfyUI 版本（检查设置中的关于页面）
Python 版本：python --version
PyTorch 版本：python -c "import torch; print(torch.__version__)"
GPU 型号和驱动程序版本

操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等）
ComfyUI 版本（检查设置中的关于页面）
Python 版本：python --version
PyTorch 版本：python -c "import torch; print(torch.__version__)"
GPU 型号和驱动程序版本

# 系统信息
systeminfo | findstr /C:"OS Name" /C:"OS Version"

# GPU 信息
wmic path win32_VideoController get name

# Python 和 PyTorch 信息
python --version
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

# 系统信息
systeminfo | findstr /C:"OS Name" /C:"OS Version"

# GPU 信息
wmic path win32_VideoController get name

# Python 和 PyTorch 信息
python --version
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

# 系统信息
uname -a

# GPU 信息（Linux）
lspci | grep VGA

# Python 和 PyTorch 信息
python --version
python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}')"

错误的详细信息

问题的清晰描述
重现问题的步骤
预期行为与实际行为
如果可以，提供截图或复现过程的屏幕录制

错误消息

控制台/终端的完整错误文本
浏览器控制台错误（F12 → 控制台选项卡）
任何崩溃日志或错误对话框

其他上下文

已安装的自定义节点列表
重现问题的工作流文件（.json）
最近的更改（新安装、更新等）

社区资源

官方论坛： forum.comfy.org
Discord： ComfyUI Discord 服务器
Reddit： r/comfyui
YouTube： ComfyUI 教程

对于影响许多用户的紧急问题，请查看我们的状态页面和官方 Twitter以获取公告。

开始使用

界面指南

教程示例

故障排除

社区

如何排查和解决 ComfyUI 中出现的错误

自定义节点故障排除指南

常见问题与快速修复

ComfyUI 无法启动

生成失败或产生错误

性能缓慢

安装过程中出现的问题

桌面应用问题

手动安装问题

Linux 特定问题

模型相关问题

网络和 API 问题

API 节点不工作

连接问题

硬件特定问题

NVIDIA GPU 问题

AMD GPU 问题

Apple Silicon (M1/M2/M3) 问题

获取帮助和报告错误

报告错误之前

如何有效报告错误

对于 ComfyUI 核心问题

对于桌面应用问题

对于前端问题

对于自定义节点问题

在 issue 中你需要提供的信息

社区资源

开始使用

界面指南

教程示例

故障排除

社区

自定义节点故障排除指南

​常见问题与快速修复

​ComfyUI 无法启动

​生成失败或产生错误

​性能缓慢

​安装过程中出现的问题

​桌面应用问题

​手动安装问题

​Linux 特定问题

​模型相关问题

​网络和 API 问题

​API 节点不工作

​连接问题

​硬件特定问题

​NVIDIA GPU 问题

​AMD GPU 问题

​Apple Silicon (M1/M2/M3) 问题

​获取帮助和报告错误

​报告错误之前

​如何有效报告错误

​对于 ComfyUI 核心问题

​对于桌面应用问题

​对于前端问题

​对于自定义节点问题

​在 issue 中你需要提供的信息

​社区资源

常见问题与快速修复

ComfyUI 无法启动

生成失败或产生错误

性能缓慢

安装过程中出现的问题

桌面应用问题

手动安装问题

Linux 特定问题

模型相关问题

网络和 API 问题

API 节点不工作

连接问题

硬件特定问题

NVIDIA GPU 问题

AMD GPU 问题

Apple Silicon (M1/M2/M3) 问题

获取帮助和报告错误

报告错误之前

如何有效报告错误

对于 ComfyUI 核心问题

对于桌面应用问题

对于前端问题

对于自定义节点问题

在 issue 中你需要提供的信息

社区资源