依赖安装提速10倍：comfy-cli 的 --fast-deps 与 --uv-compile 统一依赖解析原理深度解析

依赖安装提速10倍：comfy-cli 的 --fast-deps 与 --uv-compile 统一依赖解析原理深度解析

【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli

comfy-cli 是一款 ComfyUI 命令行管理工具，一条命令即可完成安装、自定义节点与模型管理。其中--fast-deps与--uv-compile两个开关，将依赖安装从"逐节点 pip 串行安装"升级为"基于 uv 的批量解析"，速度最高可提升 10 倍，并根治自定义节点之间常见的依赖版本冲突问题。本文带你快速理解它们的原理与用法。

为什么 ComfyUI 依赖安装又慢又容易冲突？

ComfyUI 的生态建立在成百上千个自定义节点（custom nodes）之上，而每个节点都自带一份独立的requirements.txt。默认的安装方式是逐节点执行pip install，这会带来三个经典痛点：

痛点	具体表现
🐌 速度慢	pip 的解析算法保守，逐个安装时重复下载、反复解析
💥 版本冲突	节点 A 需要xformers==0.0.21，节点 B 需要0.0.23，后装者直接覆盖先装者
❓ 结果不可复现	安装顺序不同，最终环境不同

comfy-cli 针对这个问题提供了两条加速路径：内置的--fast-deps与统一的--uv-compile，二者都基于uv pip compile做一次全局解析，再一次性安装。

四种依赖策略一览

策略	开关	解析器位置	行为
默认	（无）	cm_cli	逐节点pip install
快速依赖	--fast-deps	comfy-cli 内置DependencyCompiler	comfy-cli 侧批量uv pip compile
不装依赖	--no-deps	cm_cli	跳过依赖安装
统一解析	--uv-compile	ComfyUI-ManagerUnifiedDepResolver	cm_cli 侧批量解析 + 跨节点冲突检测

--fast-deps原理：内置的 uv 依赖编译器

--fast-deps把依赖安装从 pip 切换到 comfy-cli 内置的DependencyCompiler（源码见 comfy_cli/uv.py），整体流程分三步：

1. 收集需求：扫描工作区与所有节点目录中的requirements.txt、pyproject.toml、setup.cfg、setup.py（Find_Req_Files）；
2. 统一编译：把所有需求文件合并，一次性执行uv pip compile完成全局版本解析，并注入 GPU 对应的 PyTorch 源（--torch-backend）；
3. 批量安装：用uv pip install一次装完，而非逐节点串行。

它的核心优势：

• ⚡更快：uv 以 Rust 实现，依赖解析与下载并行化，比 pip 快一个数量级；
• 🎯零依赖门槛：只需要uv，不需要安装 ComfyUI-Manager；
• 💬冲突不崩溃：遇到版本冲突时，交互式提示你选择保留哪个版本（见Compile中的resolve_strategy="ask"分支），而不是直接报错退出。

支持的命令：comfy install、comfy node install、comfy node reinstall、comfy node restore-snapshot。

comfy install --fast-deps comfy node install comfyui-impact-pack --fast-deps

--uv-compile原理：ComfyUI-Manager 统一依赖解析

如果说--fast-deps是"comfy-cli 自己干"，那么--uv-compile就是"请专业团队干"——它委托 ComfyUI-Manager（v4.1+）的UnifiedDepResolver完成解析。

comfy-cli 采用pass-through（透传）架构：execute_cm_cli()在 comfy_cli/command/custom_nodes/cm_cli_util.py 中只需给 cm_cli 子进程命令追加--uv-compile参数，真正的解析全部由 Manager 侧完成。这样设计的好处是 comfy-cli 无需重复实现解析逻辑，Manager 升级时也不需要同步修改。

相比--fast-deps，它多了一个杀手锏——跨节点冲突检测：

• 能定位出哪几个节点包之间存在不兼容的依赖，以及冲突的具体原因（节点归因）；
• 冲突报告直接指向节点，排障成本大幅降低。

它覆盖 7 个节点命令：install、reinstall、update、fix、restore-snapshot、restore-dependencies、install-deps，并提供独立的存量同步命令：

comfy node install comfyui-impact-pack --uv-compile comfy node uv-sync # 对已安装的所有节点批量重新解析

一键设为默认值

不想每次手动加开关？一条命令即可全局开启：

comfy manager uv-compile-default true

该设置写入配置文件~/.config/comfy-cli/config.ini的[DEFAULT]段（键名uv_compile_default，源码见 comfy_cli/config_manager.py）。开启后所有节点命令自动走--uv-compile，也可用--no-uv-compile对单次命令临时关闭。

三态标志位：开关是如何被解析的？

--uv-compile在 7 个命令中都被设计为三态参数（实现见 comfy_cli/command/custom_nodes/command.py 的_resolve_uv_compile）：

用户输入	参数值	解析结果
--uv-compile	True	强制开启
--no-uv-compile	False	强制关闭
不写	None	回退查配置文件默认值

优先级规则很直白：显式参数 > 配置默认。一个值得注意的细节：当配置默认开启、但用户显式传了--fast-deps时，不会报错，而是静默地让--fast-deps胜出——因为"用户当前这条命令的意图"永远优先于全局默认。

互斥规则

--uv-compile、--fast-deps、--no-deps三者互斥，同时使用会直接报错退出：

Cannot use --fast-deps and --uv-compile together

✅例外：comfy node restore-snapshot命令中，--fast-deps与--uv-compile是同义词（cm_cli 的 restore-snapshot 没有--no-deps，而--uv-compile内部已隐含 no-deps 语义），此时冲突的组合反而是--fast-deps --no-uv-compile。

如何选择？一张表说清楚

维度	--fast-deps	--uv-compile
解析器	comfy-cli 内置DependencyCompiler	ComfyUI-ManagerUnifiedDepResolver
覆盖范围	comfy install+ 节点安装/重装/恢复快照	7 个节点命令
冲突处理	交互提示手动选版本	自动检测并归因到具体节点
可设为默认	否	是（uv-compile-default）
前置要求	仅需uv	ComfyUI-Manager v4.1+

选型建议：

• 🚀 全新安装 ComfyUI 环境 →comfy install --fast-deps
• 🧩 Manager v4.1+ 用户管理节点 → 优先--uv-compile（推荐）
• 🧩 老版本 Manager → 回退使用--fast-deps

版本兼容性说明

comfy-cli	ComfyUI-Manager	行为
当前版本	v4.1+	--uv-compile正常工作
当前版本	v4.0 及以下	cm_cli 返回"未知标志"错误（comfy-cli 不做版本探测）
旧版 comfy-cli	任意版本	无--uv-compile开关，原有行为不变

不加开关、不开配置时，行为与之前完全一致（逐节点 pip 安装），完全向后兼容。

总结

comfy-cli 用两种机制解决了同一个问题——ComfyUI 自定义节点依赖"装得慢、装得乱"：

• --fast-deps：内置DependencyCompiler，靠uv pip compile批量解析，轻量、零额外依赖，适合全新安装；
• --uv-compile：透传给 ComfyUI-Manager 的统一解析器，跨节点冲突自动归因，适合长期管理大量节点，并可一键设为默认。

理解"先编译、再安装"这一统一依赖解析思路后，你会发现：依赖冲突不再是玄学，而是一步可检测、可定位的工程问题。🎉

【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli