工作流环境搭建

本指南是一套经过实战检验的 SOP（标准操作流程），用于搭建 ComfyUI 环境以运行一批工作流。目标很明确：达到插件和依赖全部解决的状态，剩下的唯一问题就是缺少模型文件。

这是我们在远程修复服务中帮助用户时使用的方法论。

核心原则

先启动核心，再审查缺口。先修节点，再修依赖。先做运行时验证，再考虑模型问题。

如果颠倒这个顺序，你会浪费大量时间：

• 在 ComfyUI 还无法启动时就安装依赖 — 让环境变得更混乱
• 混淆前端节点和后端节点 — 以为插件没有安装
• 混淆缺失节点和缺失模型 — 在错误的方向上排查
• 看到插件文件夹存在就认为它能正常工作 — 它可能导入失败

七个阶段

整个过程遵循固定顺序。不要跳过或调换阶段顺序。

阶段 1：搭建基础环境

目标： 获得一个干净的 ComfyUI 实例，确认 Python、PyTorch 和 CUDA 正常工作。

操作步骤：

1. 创建一个全新的 ComfyUI 目录 — 不要在旧的整合包上继续堆叠插件
2. 如果你已有可用的 Python 运行时且 PyTorch + CUDA 配置正常，可以复用
3. 做一次最小化启动测试

验证方法：

• 访问 http://127.0.0.1:8188/system_stats — 应返回包含 Python 版本、PyTorch 版本和 GPU 信息的系统信息
• 如果不能正常工作，在此停下。先修复基础环境再继续

为什么这个顺序： 如果基础环境无法启动，其他一切都是噪音。参见系统要求和安装指南了解基础环境搭建。

阶段 2：审查工作流和缺失节点

目标： 建立一份具体的缺失清单 — 而非猜测。

操作步骤：

1. 递归扫描你的工作流目录（不只是顶层文件）
2. 从工作流 JSON 文件中提取所有节点类型
3. 排除不需要后端注册的纯前端节点：
   • Note、Reroute、MarkdownNote
   • Fast Groups Muter (rgthree)、Fast Groups Bypasser (rgthree)
   • PrimitiveNode、GetNode、SetNode
   • 以 workflow> 开头的节点（这些是工作流内部的包装器）

验证方法： 你能准确列出每个工作流缺少哪些后端节点。

为什么这个顺序： 如果没有列出缺失的内容，你就无法知道需要安装哪些插件。

阶段 3：将缺失节点映射到插件

目标： 将"缺少节点 X"转化为"需要安装插件仓库 Y"。

识别节点来源的优先顺序：

1. 检查工作流 JSON 中的 cnr_id（ComfyUI Node Registry ID）
2. 检查 Node name for S&R（搜索和替换名称）
3. 检查你现有的 custom_nodes/ 中是否已有仓库覆盖该节点
4. 检查 ComfyUI-Manager 的已安装包信息
5. 检查 Manager 的 extension-node-map.json 和 nodename_pattern 规则
6. 最后手段：搜索 GitHub、镜像站或旧的整合包

关于节点映射的深入说明，请参见插件管理。

常见陷阱：

• 同名节点，不同仓库： ApplyFBCacheOnModel 来自 Comfy-WaveSpeed，而不是 WaveSpeedAI/wavespeed-comfyui
• 仓库迁移： 旧的 URL 可能已失效 — 检查作者是否有新仓库
• 平台原生节点： 像 LibLibOptions、LibLibVision 这样的节点是云平台节点 — 没有对应的本地插件

阶段 4：分批安装插件

目标： 注册节点，同时不破坏已有的功能。

操作步骤：

1. 从覆盖最多缺失节点的插件开始
2. 每批安装后，重启 ComfyUI 并检查日志中的 IMPORT FAILED
3. 如果有导入失败，不要继续安装 — 先诊断问题

关键规则：

• 优先从现有整合包中复用插件，而不是重新 git clone
• 使用浅克隆以节省时间：git clone --depth 1 --filter=blob:none --single-branch
• 添加 GIT_LFS_SKIP_SMUDGE=1 以避免在克隆时下载大型模型文件
• 克隆后，验证仓库是否健康 — 有些仓库对源代码文件使用 Git LFS，这意味着你获得的是指针文本而非真正的代码（参见插件管理 — Git LFS 陷阱）

阶段 5：修复依赖冲突

目标： 从"插件存在"升级到"插件可以导入和注册"。

操作步骤：

1. 检查 ComfyUI 启动日志中的 IMPORT FAILED
2. 检查 Manager 的失败信息：/v2/customnode/import_fail_info_bulk
3. 运行 pip check 查找损坏的依赖关系
4. 用最小化的版本锁定来修复 — 不要做大范围升级

完整的依赖冲突解决指南，请参见依赖冲突。

关键规则：

• 保护你的核心运行时。 绝不能让插件的 requirements.txt 将 torch、torchvision、numpy 或 pillow 拖到不兼容的版本
• 使用 uv 代替 pip 以加快安装速度：uv pip install -r requirements.txt
• 注意自动更新器： 某些插件（如 BizyAir）会在启动时自动更新依赖，悄悄破坏你的环境。使用环境变量来禁用
• 声明中的拼写错误： 插件作者有时会拼错包名（如 libros 写成了 librosa）。不要修改他们的源代码 — 单独记录正确的映射关系

常见依赖陷阱：

• BizyAir 可能污染 starlette 版本
• mediapipe + setuptools + protobuf 有严格的兼容性要求
• nunchaku 需要与你的 Python + PyTorch + CUDA 组合精确匹配的预编译 wheel
• diffusers + transformers + huggingface-hub + accelerate 必须保持在兼容的版本组合中

阶段 6：最小化兼容性补丁

目标： 处理插件代码本身与你的 ComfyUI 版本不兼容的情况。

原则：

• 只做最小的必要修改
• 目标是恢复节点注册，而非重写业务逻辑
• 如果某个依赖是可选的且你的工作流不使用它，将其改为惰性导入而非硬性失败

实际案例：

• 将 facenet_pytorch 改为惰性检查，使其不会在导入时导致整个插件崩溃
• 添加节点名称别名，让旧工作流能找到已重命名的节点（例如 InpaintCrop → InpaintCropImproved）
• 将 ComfyUI-Manager 设为离线模式，避免启动时因网络请求而卡住

阶段 7：运行时验证

目标： 用实际运行证据来验证，而不仅仅是"文件夹存在"。

检查项目：

端点 / 命令	证明了什么
/system_stats	ComfyUI 核心正在运行，GPU 已检测到
/object_info	哪些节点已实际注册
/v2/customnode/installed	Manager 识别了哪些插件
pip check	没有损坏的依赖关系
工作流验证脚本	每个工作流所需的节点都存在

三重检查规则： 只有当三项同时通过 — 运行时端点、工作流回归测试和 pip check — 环境才是真正就绪的。如需在任何阶段进行系统化错误诊断，请使用故障排除决策树。

此阶段之后： 如果仍有错误，它们应该指向缺失的模型文件，而非插件或依赖。这就是你知道环境搭建完成的标志。

核心原则

1. 不要在旧的整合包上继续堆叠插件 — 从干净的基础环境开始
2. 不要凭插件名称猜测节点来源 — 使用工作流证据和运行时证据
3. "文件夹存在" ≠ "安装完成"
4. "节点已注册" ≠ "依赖健康"
5. "缺失模型" ≠ "插件故障" — 学会区分它们
6. 不要为了你的工作流根本不使用的可选依赖而牺牲环境稳定性
7. 所有结论必须有运行时 API 和回归脚本的支持

需要专家帮助？

搭建复杂的工作流环境正是我们远程修复服务的专长。如果你在任何阶段遇到困难，我们的专家可以通过屏幕共享实时诊断和解决问题 — 通常在 30 分钟内完成。