依赖冲突

依赖冲突是 ComfyUI 环境的头号隐形杀手。一个插件安装了一个包，那个包降级了 PyTorch，然后一切都不工作了。本指南教你如何诊断、修复和预防这些问题。

理解问题

ComfyUI 插件是独立的 Git 仓库，每个都有自己的 requirements.txt。当你安装了 20 个以上的插件时，它们的依赖声明经常会冲突：

• 插件 A 需要 numpy>=2.0
• 插件 B 需要 numpy<2.0
• 插件 C 需要 pillow>=10.3
• 插件 D 需要 pillow<10.0

这些是来自生产环境中 ComfyUI 的真实案例。

第一步：诊断

检查导入失败

查看 ComfyUI 启动日志中包含 IMPORT FAILED 的行：

IMPORT FAILED: ComfyUI-TeaCache
  AttributeError: module 'comfy.model_sampling' has no attribute '_precompute_freqs_cis'

这告诉你哪个插件失败了以及原因。参见故障排除决策树了解对这些错误进行系统分类的方法。

使用 pip 检查

pip check

这会显示所有损坏的依赖关系。输出示例：

colour-science 0.4.6 requires numpy>=2, but you have numpy 1.26.4
opencv-python 4.10.0 requires numpy>=2, but you have numpy 1.26.4

检查 Manager 的失败信息

如果 ComfyUI 正在运行，访问：

http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk

这会返回一个 JSON 列表，显示哪些插件导入失败及原因。

第二步：分类问题

并非每个 pip check 警告都是真正的问题。对每个问题进行分类：

硬性阻塞（立即修复）

这些会阻止插件加载：

• torch 版本不匹配 — CUDA 构建版本错误
• 插件直接导入的包缺失
• 两个插件要求同一个包的不重叠版本

软性偏移（监控，不修复）

这些会出现在 pip check 中但实际上不会造成任何影响：

• 某个包声明需要 numpy>=2 但在 numpy 1.26.4 下工作正常
• 可选子依赖的版本不匹配

经验法则： 如果 ComfyUI 能启动、插件能加载、你的工作流能运行 — 那就是软性偏移。

声明错误（绕过即可）

有时插件作者在依赖文件中会犯错：

• 拼写错误：libros 写成了 librosa，requirements-parserx 写成了 requirements-parser
• 不可能的组合：同一仓库中一个文件声明 pillow>=10.3，另一个文件声明 pillow<10.0

不要通过编辑插件源代码来修复这些问题。记录下解决方法即可。

第三步：修复

规则 1：保护你的核心运行时

以下包绝不能被插件安装意外降级：

在安装任何插件依赖之前，检查它们是否会更改这些包：

pip install -r requirements.txt --dry-run

规则 2：使用最小化修复

不要做大范围升级。锁定特定版本：

# 不好：升级所有内容，可能破坏其他插件
pip install -U transformers

# 好：锁定到已知可用的版本
pip install transformers==4.57.6

规则 3：对棘手的包使用 --no-deps

某些包会尝试安装自己版本的 PyTorch：

# 这会尝试安装 torch，可能破坏你的 CUDA 构建
pip install nunchaku

# 这只安装包本身
pip install nunchaku --no-deps

规则 4：使用预编译 wheel

对于需要编译的包（如 nunchaku、insightface、dlib），不要在 Windows 上尝试从源码构建。找到预编译的 wheel：

# 精确匹配 Python + PyTorch + CUDA 组合的 wheel URL
pip install https://github.com/nunchaku-ai/nunchaku/releases/download/v1.0.1/nunchaku-1.0.1+torch2.8-cp312-cp312-win_amd64.whl

规则 5：不需要的就不安装

如果插件声明了一个你的工作流不使用的可选依赖：

• 不要安装 — 它可能破坏环境稳定性
• 例如：facenet-pytorch 对 PuLID 来说是可选的。如果你的工作流不使用 FaceNet 路径，跳过它是正确的选择
• 例如：dlib 和 tb-nightly 经常被声明但实际工作流很少需要

常见冲突解决方案

BizyAir 污染 starlette

问题： BizyAir 在启动时自动更新依赖，改变 starlette 版本。

修复：

pip install starlette==0.37.2 sse-starlette==2.1.3

同时设置以下环境变量来防止未来的自动更新：

BIZYAIR_SKIP_UPDATE=1

HuggingFace 栈版本漂移

问题： diffusers、transformers、huggingface-hub 和 accelerate 必须保持在兼容的版本组合中。

修复： 一起安装它们：

pip install diffusers>=0.35,<0.36 transformers>=4.54,<5 huggingface-hub>=0.30 accelerate>=1.10

numpy 2.x vs 1.x 之争

问题： 新的包需要 numpy>=2，但 FluxTrainer 和一些视频插件需要 numpy 1.26.x。

修复： 保持 numpy==1.26.4，接受 pip check 的警告作为软性偏移。一切仍然正常工作。

xformers 破坏 torch

问题： 安装错误版本的 xformers 会拉入不同的 torch 构建。

修复： 只在有经过验证的兼容组合时才安装 xformers：

如果你的配置没有兼容的版本，请改用 --use-pytorch-cross-attention。

恢复：当你的环境已损坏

如果错误的安装已经破坏了你的核心包：

如果 PyTorch 和 CUDA 还能正常工作，但 ComfyUI 自己的核心依赖缺失，先看 ComfyUI 便携版依赖损坏后，如何不重装 Torch 修好启动。不要一上来运行会替换 GPU 栈的大范围命令。

方案 1：重新安装核心包

pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
pip install numpy==1.26.4 pillow==12.1.1

方案 2：从头开始（终极方案）

如果环境损坏到无法恢复：

1. 删除虚拟环境 / python_embeded 文件夹
2. 从便携版安装包重新解压或重新运行桌面应用安装程序
3. 逐个重新安装插件，每安装一个后检查（参见自定义节点）

相关指南

• ComfyUI 便携版依赖损坏后，如何不重装 Torch 修好启动
• ModuleNotFoundError: No module named 'sqlalchemy' in ComfyUI
• comfyui-frontend-package is not installed in ComfyUI
• 插件管理 — 高级节点映射、批量管理和 Git LFS 问题
• 工作流环境搭建 — 完整的七阶段 SOP，依赖解决在第 5 阶段
• 故障排除决策树 — 系统化错误诊断
• 常见问题 — 最常见问题的快速修复

需要帮助？

多插件 ComfyUI 环境中的依赖冲突很常见。如果你陷入了依赖地狱，先下载Wonderful Launcher来自动修复环境，无需重装系统。