Wonderful Launcher 文档进阶
依赖冲突
如何在不破坏环境的前提下诊断和修复 ComfyUI 中的 Python 依赖冲突。
依赖冲突是 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：保护你的核心运行时
以下包绝不能被插件安装意外降级：
| 包名 | 为什么关键 |
|---|---|
torch / torchvision / torchaudio |
核心 GPU 计算。版本错误 = 一切不工作 |
numpy |
几乎每个插件都依赖它 |
pillow |
图像处理基础 |
opencv-python |
ControlNet、人脸检测等众多工作流使用 |
transformers / diffusers / huggingface-hub |
模型加载和推理 |
在安装任何插件依赖之前，检查它们是否会更改这些包：
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：
| Python | torch | xformers | 状态 |
|---|---|---|---|
| 3.12 | 2.8.0+cu129 | ? | 尚无验证的组合 — 跳过 |
| 3.11 | 2.4.0+cu121 | 0.0.27.post2 | 已验证 |
如果你的配置没有兼容的版本，请改用 --use-pytorch-cross-attention。
恢复：当你的环境已损坏
如果错误的安装已经破坏了你的核心包：
方案 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：从头开始（终极方案）
如果环境损坏到无法恢复：
相关指南
需要帮助？
多插件 ComfyUI 环境中的依赖冲突是我们的专长。如果你陷入了依赖地狱，预约远程修复服务 — 我们会实时帮你解决。