ARTICLE · 1204466
插件作者自己劝你别用:ComfyUI-BrushNet-Wrapper 四道墙全拆解
ComfyUI-BrushNet-Wrapper 详细使用方法和壁垒
涂哪改哪的局部重绘神器，为什么作者自己都劝你换插件
局部重绘一直有个老大难：蒙版里的内容是补上了，但边缘一圈总有"贴上去"的痕迹，风格也对不上底模。BrushNet 用"双分支"架构解决了这个问题——把蒙版区域的像素特征直接喂给 UNet 的每一层，补出来的区域和原图浑然一体。
但这个 Wrapper 插件有个尴尬的现状：作者 kijai 自己在 README 顶置了"建议改用原生实现"。它还能用、有些场景还必须用它，但四道墙你得先知道——第一道就在安装之前。
原理——双分支拆开"改哪里"和"改成什么"
BrushNet 是腾讯 ARC 实验室与香港中文大学的论文工作（ECCV 2024，arXiv 2403.06976），定位是即插即用的图像修复模型：不用微调整个底模，像 ControlNet 一样外挂一个分支进去。
两个核心设计：①任务拆分——蒙版区域的像素特征和噪声 latent 分开处理，模型不用同时猜"哪里坏了"和"该补什么"，学习负担骤减；②逐像素控制——把蒙版特征按像素级密度注入预训练模型的全部层级，而不是只在少数层做全局引导。这就是它边缘融合明显好于普通 inpaint 的原因。
代码与权重是 Apache-2.0 许可，可以商用；但要清楚一点——模型在 LAION 通用数据上训练，官方明确说明只保证通用场景的效果，工业级应用（商品图、试穿）建议用自己数据再训。
安装——两种装法，模型自动下载
方式一：ComfyUI Manager 搜 "BrushNet"，选 ComfyUI-BrushNet-Wrapper 从 git 安装。方式二：手动克隆到 custom_nodes 后装依赖：
安装命令
cd ComfyUI/custom_nodesgit clone https://github.com/kijai/ComfyUI-BrushNet-Wrapperpip install -r requirements.txt（Portable 版在 ComfyUI_windows_portable 目录下用 python_embeded\python.exe 执行同样的 pip）
注意依赖比较重：diffusers 0.27.2+、accelerate、omegaconf——它等于往你的 ComfyUI 里塞了一整套 HuggingFace diffusers 管线。这个设计是后面所有兼容性问题的根源，也是作者最终推荐原生实现的原因。首次运行会自动从 Kijai/BrushNet-fp16 下载 fp16 权重（约 3~5GB）到 models/brushnet/，控制台刷屏属正常现象。
核心工作流——五个节点一条主线
主线四步：CheckpointLoaderSimple（SD1.5 底模）→ BrushNet Model Loader（吃进 model / clip / vae，下拉三选一权重）→ BrushNet Sampler（接原图 + 蒙版 + 正负条件）→ VAEDecode 出图。
三个必须记住的点：①掩码与原图必须同尺寸，否则直接报错 Image and mask should be the same size；②权重的 ip_adapter 输入来自包内自带的 matteo 节点，不是 ComfyUI 官方 IPAdapter 系列，别接错；③重绘边缘有痕迹时，接同包的 BlendInpaint 节点做过渡融合。
同包还有两个变体 Sampler：PowerPaint BrushNet Sampler（配 PowerPaint 权重，普通 Sampler 会直接拒绝运行）和 BrushNet Sampler (ELLA)（T5 语义增强，长提示词理解更好）。
BrushNet-Wrapper 工作流：四个主线节点 + 三个变体辅助节点
参数与选型——三个权重，三条硬规则
权重下拉三选一：brushnet_segmentation_mask 是默认推荐，用真实物体的分割形状掩码训练，常规局部重绘效果最好；brushnet_random_mask 用随机形状训练，手绘粗糙掩码更宽容；powerpaint_v2_brushnet 是 PowerPaint 权重，功能最强但必须配 PowerPaint Sampler。
采样参数在这里不走普通 KSampler 的那套逻辑：Wrapper 自带 diffusers 管线，Sampler 节点自带 scale（强度，默认 1.0）和 start_at / end_at（干预步窗口）两个专属参数，调度器也在 Sampler 里选。想精细控制就先记住这组语义，别拿文生图的经验硬套。
三个权重的掩码取向与装前硬规则
内部机制——它 patch 了 UNet，所以有兼容性雷区
Wrapper 的工作方式是给底模的前向函数打补丁（patch）：修改 UNet 的输入块、中间块和输出块，把蒙版特征逐层注入；scale 只在 start_at 到 end_at 的步数窗口内生效。理解了这一点，三个"玄学问题"就都有解释了：
①节点冲突：FreeU_Advanced、blepping 的 jank、HiDiffusion 这些节点也 patch 同一批函数——和 BrushNet 同场必打架，只能二选一。②顺序敏感：LoRA 等"改模型"的节点必须放在 BrushNet 之前，放在之后会失效或出怪结果。③上采样失效：BrushNet 与 KSampler 之间插 latent 上采样会产出畸变图——放大请用底模走独立流程，别夹在中间。
另外它自带完整 diffusers 管线，只认 SD1.5（固定 v1-inference.yaml 配置）——SDXL 想用 BrushNet 只能换原生版 nullquant/ComfyUI-BrushNet，这也是作者 README 里那句"推荐原生实现"的直接原因。
四道墙——从跑通到跑对的壁垒
墙一：兼容墙（Wrapper 特有，最硬）
自带 diffusers 管线带来三连击：只支持 SD1.5；普通 KSampler 参数不适用（Sampler 自带 scheduler 和 scale 体系）；patch 机制与 FreeU_Advanced / jank / HiDiffusion 冲突、与 LoRA 等模型修改节点有严格顺序要求。最关键的背景：kijai 已在 README 顶置更新，建议改用原生实现 nullquant/ComfyUI-BrushNet——这个 Wrapper 已两年多没更新，属于"半退役"状态。新装用户建议直接上原生版；只有维护 2024 年的旧工作流时才需要它。
墙二：模型与掩码墙
三个坑叠一起：权重文件名全部相同（都叫 diffusion_pytorch_model.safetensors）——多权重必须分目录存放并改名，否则互相覆盖，下拉框里显示的根本不是你以为的那个；SD15 与 SDXL 权重不通用，混用直接报错；掩码质量决定出图质量——分割式掩码（贴着物体轮廓）远好于随手涂的怪形状，掩码与原图尺寸必须一致。PowerPaint 权重还有专属陷阱：必须配 PowerPaint Sampler，接普通 Sampler 直接拒绝运行。
墙三：参数墙
scale / start_at / end_at 是它自己的参数体系。最经典的坑：PowerPaint v2 升级（2024 年 5 月）后，旧工作流里 end_at 被存成 1，出图直接崩——官方修复方式就是把它改回大值（默认 10000）。老工作流突然不对劲，先查这个。PowerPaint 的 fitting 控制提示词融合度（0.3~1.0），结果跟提示词"打架"就调低；五档 function 各有配套提示词技巧（object removal 加 empty scene blur，扩图加 empty scene），不加这些词效果会打折。
墙四：显存与质量墙
PowerPaint 显存占用高于普通 BrushNet，小显存开 save_memory=max（用速度换显存）；GTX 16 系等老卡 fp16 出乱码就换 float32。大图小掩码是最常见的 OOM 场景——别整图重绘，用 CutForInpaint 裁出局部修完再贴回去。质量层面：结果高度依赖底模风格匹配（真人照片配动漫底模必乱）；文字重绘容易糊，用 BlendInpaint 过渡；前景物体移除经常有残留（官方文档承认的局限），要靠负向提示词"描述要删的东西 + 正向描述空场景"来救；latent 尺寸必须等于原图除以 8，不匹配不会报错而是直接出乱图——排查时优先对一下尺寸。
PowerPaint 五档任务与参数甜区
常见问题排查——先查这里再骂插件
三条通用心法
★ 一句话口诀
权重分目录改名存，掩码贴轮廓同尺寸；LoRA 在前 BrushNet 在后，上采样别夹中间；老工作流先查 end_at，大图小掩码用 CutForInpaint。
写在最后——2026 年还要不要用 Wrapper
直接给结论：新装用户不要再用 Wrapper，去装原生版 nullquant/ComfyUI-BrushNet——这是作者 kijai 亲口写的建议，原因就是前面说的自带 diffusers 管线那堆兼容性问题。Wrapper 目前的存在价值，是维持 2024 年老工作流能继续跑，以及 ELLA / PowerPaint 组合等少数特殊玩法。
但更大的趋势要说透：局部重绘这条赛道已经被指令式编辑模型改写了。FLUX Fill、Qwen-Image Edit、FLUX Kontext 这类模型不用画蒙版、一句话就能改，在多数日常场景里体验更好。BrushNet 体系的不可替代性只剩三处：掩码级精准控制（指令模型说不清的精细区域）、SD1.5 生态的低成本批量修图、以及与 ControlNet / LoRA 组合的确定性流水线。需求落在这三处，BrushNet 仍是最优解；不在，直接上指令编辑模型更省心。
总结
BrushNet = 双分支拆任务 + 蒙版特征逐层注入（边缘融合好的原因）四道墙：兼容（SD1.5 限定 + patch 冲突）· 模型（同名权重 + 掩码质量）· 参数（end_at 陷阱）· 显存（CutForInpaint + save_memory）选型：新装用原生版；老工作流留 Wrapper；掩码级精准控制仍是它不可替代的场景。
本文基于 kijai/ComfyUI-BrushNet-Wrapper 与 TencentARC/BrushNet 官方仓库及社区实测整理许可信息仅供参考，商用前请自行核实许可原文
