节点式工作流接入未合并控制网络特性的排错

一、环境隔离与版本记录

本文以 ComfyUI 作为节点式生成工作流的主程序。未合并特性通常还没有进入正式发布版本，节点名称、参数和依赖都可能随补丁更新而变化。因此第一步是把测试环境与现有环境分开，并记录每个基线版本。

适用边界：本文适用于测试机、个人开发机或独立容器。不适用于在生产环境直接使用未合并补丁，也不适用于来源不明的补丁或扩展。

建议复制现有目录，或从官方仓库新建一个独立目录，并创建独立虚拟环境：

git clone https://github.com/comfyanonymous/ComfyUI.git comfy-test
cd comfy-test
python -m venv .venv
source .venv/bin/activate        # Windows 使用 .venv\Scripts\activate
pip install -r requirements.txt

开始修改前，把下表内容写入 version-manifest.md，作为回滚依据。

记录项	获取方式	说明
主程序标签	git describe --tags	没有标签时记录提交号
主程序提交号	git rev-parse HEAD	完整 40 位哈希
Python 版本	python --version	与虚拟环境一致
依赖清单	pip freeze > requirements.lock.txt	用于还原依赖
已安装扩展	列出 custom_nodes 目录下的子目录及其 git rev-parse HEAD	记录扩展版本
模型文件哈希	PowerShell 用 Get-FileHash，Linux 和 macOS 用 sha256sum	防止同名但版本不同的模型混用
工作流基线	保存未修改的工作流 JSON	用于对比输出

二、合并未合并补丁与冲突处理

补丁的兼容版本以补丁作者在 Pull Request 描述中的说明为准。文中不预设固定版本号，请以实际 PR 信息为准。

1. 在 GitHub 上找到补丁所在的 Pull Request，记下编号，并确认描述中写明的兼容主程序版本。
2. 把 <PR号> 替换为实际编号，拉取到本地分支：

git status                                   # 确认工作区干净，或先用 git stash 暂存本地改动
git fetch origin pull/<PR号>/head:test/controlnet-pr-<PR号>
git switch test/controlnet-pr-<PR号>

1. 查看补丁改动的文件范围：

git diff <基线标签> --stat

1. 按文件类别处理冲突。核心逻辑文件（如 comfy/ 目录下的模型加载和采样相关代码）不要手动硬改，如果冲突严重，应切换到 PR 描述中的兼容版本重新拉取。配置示例文件（如 extra_model_paths.yaml.example）只合并模型路径，保留本地模型目录。依赖声明文件（requirements.txt）需要对比新增依赖，确认来源可信后再安装。

2. 合并后安装依赖，并保存新的依赖清单：

pip install -r requirements.txt
pip freeze > requirements.patched.txt

处理冲突时，禁止使用 git reset --hard 或 git checkout -- <文件> 强制覆盖，这些命令会丢失本地改动。需要保留的改动可以先用 git stash push -m "local-config" 暂存，回滚后再用 git stash pop 恢复。

三、安装扩展与配置关键参数

1. 启动主程序：python main.py。观察控制台输出。若某个自定义节点目录加载失败，日志会出现 IMPORT FAILED 并附带该目录名。
2. 加载目标工作流。若弹出缺失节点列表，记录每个节点的类型名和所属扩展。
3. 安装辅助扩展。常用做法是通过 ComfyUI-Manager 搜索并安装对应的预处理节点集合，例如 comfyui_controlnet_aux。也可以手动克隆到 custom_nodes 目录，然后安装其依赖：

cd custom_nodes
git clone <扩展仓库地址>
pip install -r <扩展目录>/requirements.txt

安装前先查看扩展仓库的 install.py（如果有）和依赖清单。这些脚本会在本机执行，只安装可信来源的扩展。

4