ComfyUI 依赖冲突：无需重装即可修复

如果你搜索的是 comfyui dependency conflicts、sensevoice-onnx setuptools conflict comfyui、custom node broke environment 或 pip install broke comfyui，简短的答案是：

不要先重新安装。找出哪个插件导入或包变更破坏了环境，然后修复尽可能小的那一层。

如果你的 pip check 输出恰好是 sensevoice-onnx requires setuptools<=65.0，请使用专用的 SenseVoice-ONNX setuptools 冲突修复指南，按照最小修复路径操作。

依赖冲突是许多 ComfyUI 环境的隐形杀手。一个插件安装了某个包，该包改变了 PyTorch、NumPy、OpenCV 或其他共享库，结果昨天还能正常运行的工作流今天突然无法运行。

代价高昂的不只是那个损坏的包，而是随之而来的恢复循环：

• 查看日志
• 随机尝试 pip install 命令
• 重启 ComfyUI
• 又破坏了别的东西
• 开始怀疑自己是否需要重装所有内容

本指南教你如何诊断、修复并预防这些问题，而不是将重装当作默认答案。

值得尽早识别的冲突模式

以下特征出现频率足够高，值得一眼认出：

快速答案

修改包之前的案例审查分级

已审查的修复案例表明，许多"依赖冲突"会话实际上比包冲突早一层或晚一层。在运行安装命令之前，请先进行以下边界检查：

只有当故障确实出现在共享 Python 包层时，才继续阅读本页。如果下一个阻塞项是模型文件、节点注册表或 Torch CUDA 构建，修复包只会让环境更嘈杂，却无法解决工作流问题。

常见冲突特征

近期支持案例显示，用户通常直接搜索 pip check 中的具体包名，而不是搜索"依赖冲突"这类抽象词语。以下示例有参考价值，因为它们指向了改变共享环境的包族。

所有这些情况背后的重要规律是相同的：pip check 中的一行输出是线索，而不是自动执行的命令。先确认 ComfyUI 是否真的报错、哪个插件导入失败，以及你所需要的工作流是否真的用到了那个包。

安装任何东西之前

先做这四件事：

1. 从启动终端记录精确的错误信息。
2. 记录你最后安装的插件或依赖项。
3. 确认哪个 Python 实际启动了 ComfyUI。
4. 检查故障是核心运行时损坏、插件导入失败，还是只是无害的声明警告。

这个顺序能省去大量无谓的修复工作。

实用的分级处理顺序

当环境之前正常、插件操作后才出现问题时，以下顺序通常最安全：

1. 检查 IMPORT FAILED
2. 在真实的 ComfyUI Python 中运行 pip check
3. 判断问题是硬性阻塞还是软性漂移
4. 在处理插件包之前先保护 Torch/CUDA
5. 修复尽可能小的包集合

理解问题根源

ComfyUI 插件是独立的 Git 仓库，各自拥有 requirements.txt。安装多个插件时，它们的依赖声明可能发生冲突：

• 一个插件需要 numpy>=2
• 另一个旧插件只能用 numpy<2
• 一个视频节点需要更新版本的 transformers
• 一个人脸或姿态节点引入了 OpenCV、ONNX Runtime 或 Windows 原生 wheel
• 一个加速包需要特定的 Python、PyTorch、CUDA 或 GPU 架构

重要的是这条链路：

1. 工作流请求后端节点类。
2. 自定义节点插件在启动时注册这些类。
3. 插件导入依赖于 Python 包和原生 wheel。
4. 原生 wheel 可能依赖于 Python、PyTorch、CUDA、cuDNN、GPU 架构和 Windows 运行时库。

如果你修复的是错误的那一层，环境只会变得更混乱，而原始问题依然存在。

大多数修复失败的原因，是用户直接从可见症状跳到随机安装包，而没有先判断究竟是哪一层出了问题。

第一步：诊断

检查导入失败

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

IMPORT FAILED: ComfyUI-ExampleNode
ModuleNotFoundError: No module named 'somepackage'

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

使用 pip 检查

在启动 ComfyUI 的相同 Python 环境中运行 pip check：

示例输出：

some-plugin 1.0 requires numpy<2, but you have numpy 2.4.4
another-package 2.0 requires pillow<11, but you have pillow 12.2.0

检查 Manager 的失败信息

如果 ComfyUI 正在运行，访问：

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

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

第二步：分类问题

并非每个 pip check 警告都是真正的问题。在安装任何东西之前，先对每个问题进行分类。

硬性阻塞

优先修复这些：

• torch 不匹配或仅有 CPU 版 Torch。如果 ComfyUI 报告 Torch not compiled with CUDA enabled，在更改插件包之前先使用 Torch CUDA 修复指南。
• 插件直接导入的缺失包，且该插件是你工作流所需的。
• 原生 wheel 导入失败，例如 DLL load failed while importing cv2。
• 两个必需插件需要同一包的不相交版本。

软性漂移

监控这些，而非急于更改环境：

• pip check 报告版本声明不匹配，但 ComfyUI 能启动、插件能导入、工作流能运行。
• 某个包只被你的工作流从未使用的功能所需要。
• 可选的加速后端缺失，但节点有正常的 PyTorch 回退。

经验法则： 如果 ComfyUI 能启动、插件已注册、工作流能运行，就不要为了让 pip check 看起来干净而"修复"警告。

声明错误

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

• 拼写错误，例如 libros 而非 librosa
• 会降级核心包的宽泛版本锁定
• 将可选包列为必需包
• 在 Linux 上正确但在 Windows 上错误的包

不要将随机编辑插件源文件作为第一反应。记录解决方案，并将修复范围保持尽可能小。

第三步：修复

规则 1：保护核心运行时

这些包不能被插件安装意外更改：

安装插件依赖之前，预览将要发生的变更：

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

如果试运行想替换 Torch、NumPy、Pillow、OpenCV 或 Hugging Face 技术栈，停下来，判断该插件是否真的需要这些更改。

规则 2：使用正确的 Python

直接使用 pip install 存在风险，因为它可能指向错误的 Python。

规则 3：使用最小修复

不要进行大范围升级：

# 有风险：在不了解影响的情况下升级共享包技术栈
python -m pip install -U transformers diffusers huggingface-hub

优先使用与精确失败导入相关的最小修复，或遵循插件作者经过测试的兼容性表。

让 ComfyUI 变得更糟的最快方式之一，就是因为一个插件失败，就对整个 Hugging Face 或图像技术栈运行大范围升级命令。

规则 4：使用正确的包名

有些错误看起来显而易见，但实际上存在包名陷阱：

规则 5：对原生包使用预构建 Wheel

对于在 Windows 上需要编译的包，使用与你的环境匹配的 wheel：

• Python 版本，例如 cp312
• PyTorch 版本（如果 wheel 与 Torch 绑定）
• CUDA 版本（如果包含 CUDA 内核）
• Windows 架构，通常为 win_amd64

这适用于 nunchaku、insightface、某些注意力内核以及其他原生加速库等包。

通常会让依赖冲突变得更糟的做法

在尚未对问题分类之前，避免以下操作：

• 按照 Reddit 或 Discord 上的旧帖子随机重装包
• 使用普通 pip install 指向错误的 Python
• 让插件在未察觉的情况下降级 Torch
• 不检查影响就将 numpy、opencv、transformers 或 diffusers 整体升级
• 用常规上游 triton 包修复 Windows 上的 Triton 错误
• 将每个 pip check 警告都当作生产环境故障来处理

常见冲突处理方法

Hugging Face 技术栈漂移

问题： diffusers、transformers、huggingface-hub 和 accelerate 通常需要保持在兼容的版本集合中。

更安全的修复： 不要盲目升级单个包。检查插件 README 或错误日志，然后在 ComfyUI 的 Python 环境中安装最小兼容集合。

NumPy 2.x 与 1.x

问题： 一些旧插件仍然期望 NumPy 1.x 的行为，而较新的包和当前的便携环境可以在 NumPy 2.x 下运行。

更安全的修复： 不要因为某篇旧指南建议锁定 NumPy 1.x 就全局降级。先确认你所需插件真的报了 NumPy 错误。如果该插件确实需要 NumPy 1.x，在隔离的环境中运行该工作流，或者只在充分了解其他插件受影响情况后再降级。

OpenCV 包冲突

问题： opencv-python、opencv-python-headless、opencv-contrib-python 和 opencv-contrib-python-headless 都提供 cv2 命名空间。安装多种版本可能覆盖文件并导致导入失败。

更安全的修复： 只保留一种版本。对于大多数 ComfyUI 后台处理场景，opencv-python-headless 是更安全的默认选择。参见 OpenCV (cv2) 缺失或冲突。

Nunchaku Wheel 不匹配

问题： Nunchaku 与硬件、Python、PyTorch、CUDA 以及 ComfyUI-nunchaku 插件流程绑定。Python 或 Torch 版本错误的 wheel 无法修复导入问题。

更安全的修复： 使用 Nunchaku 的安装流程，或使用与你的精确环境匹配的 wheel。在 ComfyUI 便携版上，使用 ComfyUI 启动日志中实际打印的 Python 可执行文件进行安装。如果可见的工作流症状是 NunchakuFluxLoraLoader、NunchakuFluxLoraStack 或 NunchakuFluxDiTLoader，先修复 ComfyUI-nunchaku 导入，而不是安装以节点命名的包。

MMCV 构建或 Wheel 失败

问题： MMCV 可能需要与你的 Python、PyTorch、CUDA 和平台匹配的 OpenMMLab wheel。如果安装程序在 Windows 上回退到源码构建，pip install mmcv 可能在自定义节点导入之前就已失败。

更安全的修复： 判断该插件需要完整的 MMCV CUDA ops 还是只需要 mmcv-lite。参见 ComfyUI MMCV 安装失败。

ONNX Runtime GPU 不匹配

问题： 当 onnxruntime-gpu 的 CUDA/cuDNN 主版本与 PyTorch 运行时技术栈不匹配时，可能会失败。

更安全的修复： CPU 版 onnxruntime 对许多姿态/人脸辅助工作流已足够。只有在需要且能够匹配 CUDA/cuDNN 系列时，才安装 GPU 版 ONNX Runtime。参见 ComfyUI 中 ONNX / ONNXRuntime 缺失。

恢复：当你的环境已经损坏

如果错误安装已损坏核心包，不要猜测通用的版本集合。

1. 记录当前 Python 路径、ComfyUI 版本、PyTorch 版本、CUDA 版本以及最后安装的插件。
2. 使用适合你 GPU 和安装类型的 Torch CUDA 修复指南 恢复 Torch。
3. 在相同环境中修复 ComfyUI 自身的依赖项。
4. 重启 ComfyUI 并确认 /system_stats 正常工作。
5. 逐一添加插件修复，每次更改后检查 IMPORT FAILED。

对于官方 Windows 便携包，这通常意味着从解压后的便携包根目录运行命令，而不是从 ComfyUI 子文件夹内部运行。

如果 PyTorch 和 CUDA 仍然正常，但 ComfyUI 核心包缺失，请在运行可能替换 GPU 技术栈的大范围命令之前，使用无需重装 Torch 即可修复损坏的 ComfyUI 便携版依赖。

在将修复标记为完成之前，请验证你真正关心的那个 ComfyUI 进程：

如果验证过程中发现新的缺失模型，停止更改包，转而走模型放置路径。

何时停止修复并拆分环境

有时真正的答案不是"再执行一条 pip 命令"。

在以下情况下考虑使用独立环境：

• 一个旧插件和一个新插件需要不相交的包版本
• 一个工作流需要旧版 NumPy / OpenCV 锁定，另一个需要更新的模型技术栈
• 一个视频或加速插件持续强制更改核心运行时

这通常比长期维护一个不稳定的共享环境更划算。

仅当恢复风险过高时才全新开始

如果环境损坏程度无法恢复：

1. 保留工作流、模型和 custom_nodes 的副本。
2. 重新解压便携包或重新运行 Desktop 安装程序。
3. 逐一重新安装插件，每次安装后检查（参见自定义节点）。

常见问题

ComfyUI 中的依赖冲突是什么？

是指某个插件、包或 wheel 以破坏另一个插件、ComfyUI 运行时或工作流的方式更改了共享依赖项。

我应该立刻重装 ComfyUI 吗？

通常不需要。先确认问题是出在 Torch、插件导入、原生 wheel，还是只是版本声明不匹配。

我应该先运行什么命令？

在启动 ComfyUI 的相同 Python 环境中运行 pip check，然后与启动日志中实际的 IMPORT FAILED 行进行比对。

为什么一个自定义节点会破坏无关的工作流？

因为许多插件共享同一个 Python 环境和包技术栈。为某个节点做出的更改可能替换许多其他节点所使用的核心包。

Wonderful Launcher 如何提供帮助

Wonderful Launcher 可帮助检查活跃的 ComfyUI 环境、保留启动证据，并将包修复与真正失败的插件或工作流关联起来。它可以引导进行更安全的恢复步骤，但依赖冲突并不总是一键修复的。

下载 Wonderful Launcher — 免费开始使用。

比重复同样的修复循环更好的选择

如果依赖冲突已成为反复出现的维护问题，更大的根本原因通常不是某一个包，而是你的环境缺乏以恢复为导向的工作流。

如果环境已经过于混乱，请先保存完整 traceback、当前 Python 路径、pip check 输出和最近一次安装命令，再按最小化修复路径继续。不要为了“清理干净”一次性重装或大范围升级。

相关指南

• 无需重装 Torch 即可修复损坏的 ComfyUI 便携版依赖
• ComfyUI 中 ModuleNotFoundError: No module named 'sqlalchemy'
• ComfyUI No Module Named 'sageattention'
• ComfyUI Triton 缺失或不可用
• ComfyUI Nunchaku 缺失
• ComfyUI MMCV 安装失败
• ComfyUI 前端包
• ComfyUI Torch 未使用 CUDA 编译
• 插件管理
• 工作流环境设置
• 故障排除决策树
• 常见问题

需要帮助？

在多插件 ComfyUI 环境中解决依赖冲突，正是以恢复为导向的工作流发挥作用的地方。如果你陷入依赖地狱，在重装之前先尝试使用 Wonderful Launcher 检查环境。

参考来源

• ComfyUI 官方自定义节点故障排除
• ComfyUI 官方模型故障排除
• ComfyUI 官方 Windows 便携版指南
• ComfyUI 官方更新指南