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

常见 ComfyUI 问题、解决方案和如何有效报告错误

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

自定义节点故障排除指南

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

​

常见问题与快速修复

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

​

ComfyUI 无法启动

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

快速修复：

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

​

生成失败或产生错误

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

快速修复：

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

​

性能缓慢

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

快速修复：

1. 降低分辨率/批次大小 - 减少图像大小或图像数量
2. 使用内存优化标志 - 请参见下方性能优化部分
3. 关闭不必要的应用程序 - 释放 RAM 和显存
4. 检查 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 个结果

​

安装过程中出现的问题

​

桌面应用问题

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

Windows

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

macOS

• “应用程序已损坏”：在安全性与隐私设置中允许应用程序
• 性能问题：在隐私设置中授予完整磁盘访问权限
• 崩溃：检查控制台应用程序以获取崩溃报告

Linux

• 缺少库：使用包管理器安装依赖项
• LD_LIBRARY_PATH 错误：PyTorch 库路径问题（见下文）

​

手动安装问题

文档可能略有过时。如果出现问题，请手动验证是否存在更新的稳定版本的 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”

解决方案：

1. 现代 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

2. 查找你拥有的库：

# 检查已安装的 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'))")

3. 为你的环境永久设置：

# 对于虚拟环境，添加到激活脚本
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

4. 替代方案：使用 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

5. 调试库加载：

# 详细库加载以查看缺失的内容
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 调用失败、超时错误、配额超出

解决方案：

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

​

连接问题

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

解决方案：

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

​

硬件特定问题

​

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

​

获取帮助和报告错误

​

报告错误之前

1. 检查是否是已知问题：

   • 搜索 GitHub Issues
   • 检查 ComfyUI 论坛
   • 查看 Discord 讨论

2. 尝试基本故障排除：

   • 使用默认工作流进行测试
   • 禁用所有自定义节点（参见自定义节点故障排除）
   • 检查控制台/终端中的错误消息

​

如何有效报告错误

​

对于 ComfyUI 核心问题

问题提交： GitHub Issues

​

对于桌面应用问题

问题提交： 桌面 GitHub Issues

​

对于前端问题

问题提交： 前端 GitHub Issues

​

对于自定义节点问题

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

​

在 issue 中你需要提供的信息

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

1. 系统信息

   从 ComfyUI 中获取

   • 操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等）

   • ComfyUI 版本（检查设置中的关于页面）

   • Python 版本：python --version

   • PyTorch 版本：python -c "import torch; print(torch.__version__)"

   • GPU 型号和驱动程序版本

     

   从命令行获取

   Windows

   # 系统信息
   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()}')"
   

   macOS/Linux

   # 系统信息
   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()}')"
   
2. 错误的详细信息

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

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

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

​

社区资源

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

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