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

ComfyUI 故障排除指南：先排除自定义节点，修复常见核心问题，并提交包含正确细节的错误报告。

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

[card] 自定义节点故障排查指南查看如何排查自定义节点导致的问题。

常见问题与快速修复

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

ComfyUI 无法启动

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

快速修复：

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

生成失败或产生错误

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

快速修复：

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

性能缓慢

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

快速修复：

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

性能优化命令：

对于低显存系统：

# 低显存模式（使用 CPU 处理文本编码器）
python main.py --lowvram

# CPU 模式（非常慢但适用于任何硬件，仅作为最后手段使用）
python main.py --cpu

提高性能：

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

# 使用优化的注意力机制
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 个结果，更快
python main.py --cache-classic   # 使用旧风格（激进）的缓存

安装过程中出现的问题

桌面应用问题

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

[tab] Windows 不支持的设备：Comfy Desktop Windows 仅支持带有 CUDA 的 NVIDIA GPU。对于其他 GPU，请使用 ComfyUI 便携版或手动安装 安装失败：以管理员身份运行安装程序，确保至少 15GB 磁盘空间 维护页面：如果下载失败，请检查镜像设置 缺少模型：迁移时模型不会被复制，仅链接。请验证模型路径

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

[tab] Linux 缺少库：使用包管理器安装依赖项 LD\_LIBRARY\_PATH 错误：PyTorch 库路径问题（见下文）

手动安装问题

[!NOTE] 文档可能略有过时。如果出现问题，请手动验证是否存在更新的稳定版本的 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 13.0）
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

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

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 积分
验证互联网连接 - 使用其他在线服务进行测试
检查服务状态 - 提供商可能正在经历停机

连接问题

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

解决方案：

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

前端问题

"Frontend or Templates Package Not Updated"（前端或模板包未更新）：

# 通过 Git 更新 ComfyUI 后，更新前端依赖
pip install -r requirements.txt

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

在 ComfyUI 设置中禁用节点验证

"Error Toast About Workflow Failing Validation"（工作流验证失败的错误提示）：

暂时在设置中禁用工作流验证
向 ComfyUI 团队报告问题

非 Localhost 访问时的登录问题：

普通登录仅在从 localhost 访问时有效
对于局域网/远程访问：在 platform.comfy.org/login 生成 API 密钥
在登录对话框中使用 API 密钥，或使用 --api-key 命令行参数

硬件特定问题

NVIDIA GPU 问题

"Torch not compiled with CUDA enabled" 错误：

# 先卸载 torch
pip uninstall torch

# 安装带 CUDA 13.0 的稳定版 PyTorch
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130

# 对于 nightly 版本（可能有性能改进）
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132

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

GPU 未被检测到：

# 检查 GPU 是否可见
nvidia-smi

# 检查驱动版本和 CUDA 兼容性
nvidia-smi --query-gpu=driver_version --format=csv

Blackwell GPU（sm_103）：生成会在第一个注意力层失败

在 Blackwell 代 NVIDIA GPU 上，PyTorch 默认的缩放点积注意力（SDPA）可能会选择 cuDNN 后端，但该后端没有适用于此架构的有效执行计划：

cuDNN Frontend error: No valid execution plans built

使用 FLUX 时，问题会出现在 UNet 的第一个注意力块上，因此不会生成任何图像。

# 使用绕开 SDPA 和 cuDNN 的手写注意力实现
python main.py --use-split-cross-attention

# Blackwell 还需要 CUDA 12.8 或更新版本的 PyTorch 构建；
# 针对 cu121 编译的构建在这些显卡上根本无法运行

[!NOTE] 在启动前通过代码禁用 cuDNN SDPA 后端并不起作用（例如在 sitecustomize.py 中调用 torch.backends.cuda.enable_cudnn_sdp(False)），因为该标记在 CUDA 初始化后不会被保留。启动参数才是可靠的解决办法。

本条目由 PR #1491 添加。

AMD GPU 问题

ROCm 支持（仅限 Linux）：

# 安装稳定的 ROCm PyTorch（撰写时为 7.2）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2

# 对于 nightly 版本（撰写时为 ROCm 7.2，可能有性能改进）
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2

不支持的 AMD GPU：

# 对于 RDNA2 或更老型号（6700、6600）
HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py

# 对于 RDNA3 显卡（7600）
HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py

性能优化：

# 启用实验性内存高效注意力（PyTorch 2.4 后不再需要）
TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention

# 启用可调优操作（首次运行慢，后续运行更快）
PYTORCH_TUNABLEOP_ENABLED=1 python main.py

Apple Silicon (M1/M2/M3) 问题

[!NOTE] 本节步骤适用于手动安装或源码安装（ComfyUI 运行在你自行准备的 Python 环境中）。支持的 Python 版本见系统要求，安装步骤见手动安装。在 Apple silicon 上使用 Comfy Desktop 时无需单独安装 Python，应用会为每个实例管理自己的 Python 环境。详见适用于 macOS 的 Comfy Desktop。

MPS 后端设置：

# 安装 Apple Silicon 的 PyTorch nightly
# 请遵循 Apple 指南：https://developer.apple.com/metal/pytorch/

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

# 启动 ComfyUI
python main.py

如果 MPS 导致问题：

# 强制 CPU 模式
python main.py --cpu

# 带内存优化
python main.py --force-fp16 --cpu

Intel GPU 问题

"Torch not compiled with CUDA enabled" 错误：

在 Intel GPU 上，此错误表示 ComfyUI 尝试使用 CUDA，因为 XPU 后端不可用。请勿按照上方针对 NVIDIA CUDA 的重新安装步骤操作。Intel GPU 使用的是 XPU，而不是 CUDA。

检查 PyTorch 是否能识别 Intel GPU：

python -c "import torch; print('XPU available:', hasattr(torch, 'xpu') and torch.xpu.is_available())"

如果输出 True，ComfyUI 会自动使用 XPU 后端。

如果输出 False：

确认你使用的是受支持的 Intel Arc GPU（Arc A 系列、Arc B 系列，或搭载 Arc Graphics 的 Core Ultra 处理器）。
安装或更新 Intel GPU 驱动程序。
使用下面的选项之一安装支持 XPU 的 PyTorch。不要安装 CUDA 版本的 wheel。

方式一：原生 PyTorch XPU 支持（Windows/Linux）：

# 稳定版 XPU wheels（推荐）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu

# Nightly XPU wheels（可能包含性能改进）
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu

# 启动 ComfyUI
python main.py

方式二：Intel Extension for PyTorch（IPEX）：

# 对于 Intel Arc A 系列显卡
conda install libuv
pip install torch==2.3.1.post0+cxx11.abi torchvision==0.18.1.post0+cxx11.abi torchaudio==2.3.1.post0+cxx11.abi intel-extension-for-pytorch==2.3.110.post0+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/

常见问题

如何使用 Docker 运行 ComfyUI？

[!NOTE] Docker： ComfyUI 不提供官方 Docker 镜像。若需在容器中运行 ComfyUI，可以使用 Docker Hub 上社区维护的镜像。这些镜像并非由 Comfy-Org 官方维护，也不受 ComfyUI 团队支持，请自行评估风险后使用。

如需在 Linux 上本地安装 ComfyUI，请遵循手动安装指南。如需使用云服务，请参见 Comfy Cloud。

获取帮助和报告错误

报告错误之前

检查是否是已知问题：
搜索 GitHub Issues
检查 ComfyUI 论坛
查看 Discord 讨论

尝试基本故障排查：
使用默认工作流进行测试
禁用所有自定义节点（参见自定义节点故障排查）
检查控制台/终端中的报错信息
如果使用 comfy-cli，尝试更新：comfy node update all

如何有效报告错误

对于 ComfyUI 核心问题

提交位置： GitHub Issues

对于桌面应用问题

提交位置： 桌面 GitHub Issues

对于前端问题

提交位置： 前端 GitHub Issues

对于自定义节点问题

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

需要提供的信息

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

1. 系统信息

[tab] 从 ComfyUI 界面获取 系统信息（可在设置的关于页面找到）： 操作系统（Windows 11、macOS 14.1、Ubuntu 22.04 等） ComfyUI 版本（检查设置中的关于页面） Python 版本：python --version PyTorch 版本：python -c "import torch; print(torch.__version__)" GPU 型号和驱动程序版本 安装方式（桌面版、便携版、手动安装、comfy-cli）

[tab] 从命令行获取 > [tab] Windows > > ``bash theme={null} > # 系统信息 > 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()}')" > ` > [tab] macOS/Linux > > `bash theme={null} > # 系统信息 > 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. 桌面应用问题

对于桌面应用问题，还需提供：

日志文件来自：C:\Users\<用户名>\AppData\Roaming\ComfyUI\logs（Windows）
配置文件来自：C:\Users\<用户名>\AppData\Roaming\ComfyUI（Windows）

3. 问题的详细信息

问题的详细信息：

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

报错信息：

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

4. 其他上下文

其他上下文：

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

社区资源

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