ControlNet是Stable Diffusion生态中最强大的控图工具之一，它依赖预处理器先把参考图转换成边缘图、深度图或姿态图，再交给ControlNet模型去引导生成过程。但不少用户遇到过这样的情况：点击预处理器预览按钮后，出来的图一片纯黑，什么都看不到。这种问题看似严重，实际上绝大多数情况都可以通过更新预处理器版本和调整输入分辨率来解决。下面我们就从这两个核心方向入手，详细分析问题的成因与修复方法。
一、预处理图全黑的常见原因分析
预处理图全黑本质上意味着预处理器没有输出有效的特征信息。要解决问题，先要搞清楚是哪个环节出了问题。第一种可能是预处理器本身报错了，但错误信息被吞掉，最终返回了一张空白图。比如深度估计模型（如Midas、Depth-Anything）依赖的权重文件没有下载完整，或者下载到了损坏的版本，预处理函数在推理阶段直接失败，只返回一个全零的数组，渲染出来就是黑色图像。
第二种可能是版本兼容性问题。ControlNet扩展（sd-webui-controlnet）的更新速度很快，而WebUI本体（AUTOMATIC1111或Forge等分支）的Python环境、PyTorch版本也在不断变化。如果预处理器扩展停留在旧版本，调用的API接口已经和当前环境不兼容，比如numpy数组维度处理方式变化、cv2函数签名调整，就可能导致输出异常。第三种则是分辨率相关的问题，这也是最容易被忽略的一种：输入图片尺寸过大或过小，会让预处理器的内部缩放逻辑进入异常分支，输出的特征图数值全部趋近于零，显示为全黑。
二、检查并更新预处理器与ControlNet扩展版本
排查的第一步是确认扩展版本。打开Stable Diffusion WebUI，进入扩展（Extensions）面板，在已安装（Installed）列表中找到sd-webui-controlnet，点击检查更新（Check for updates）并应用更改（Apply and restart）。如果你使用了独立的预处理器插件（例如sd-webui-controlnet中附带的控制网络辅助预处理器集合），同样需要一并更新。某些用户提到的Inspector类预处理器用于检查模型的分层信息，它对版本尤其敏感，旧版本在新版PyTorch下经常输出空白结果。
如果WebUI界面更新失败，可以改用命令行方式手动更新。进入扩展目录执行以下操作：
cd extensions/sd-webui-controlnet git pull pip install -r requirements.txt --upgrade
更新完成后务必完全重启WebUI，包括重新加载模型，而不是只刷新浏览器页面。重启后建议开启开发者控制台查看日志：如果预处理器报错，控制台通常会打印出具体的Python堆栈信息，例如权重文件缺失、CUDA算子不匹配等。针对报错信息去下载对应权重或调整环境，往往比盲目重装有效得多。
另外要注意权重文件的存放位置。以深度估计为例，模型文件一般应放在extensions/sd-webui-controlnet/annotator/downloads对应的子目录下。如果之前下载中断产生了损坏文件（体积明显偏小），需要删除后重新下载，损坏的权重是导致全黑输出的高频原因之一。
三、输入分辨率对预处理结果的影响
分辨率问题之所以会导致全黑，和预处理器内部的工作机制有关。大多数预处理器会先把输入图缩放到一个固定的处理尺寸（例如384或512），推理完成后再映射回原始尺寸。当输入图极端狭长、尺寸特别小（比如小于64像素），或者超大（比如4000像素以上）时，缩放过程中的插值可能让特征信息被压缩到几乎为零的数值范围。OpenCV输出的数组如果整体数值极低，渲染成图片后肉眼看上去就是黑色的。
推荐的做法是：在送入ControlNet之前，把参考图调整到512到1024像素之间，并保持宽高比合理。可以在WebUI的图生图（img2img）页面先裁剪和缩放图片，再上传到ControlNet面板。举个例子，一张2000乘3000的照片，可以先等比缩放到683乘1024再使用。经验上，512分辨率是大多数预处理器（Canny边缘、OpenPose姿态、深度估计）都比较稳定的工作区间。
如果调整后仍然偏暗但不是全黑，可以尝试在预处理器输出后手动调整对比度。部分新版ControlNet扩展在预览窗口旁提供了像素级检查工具，可以查看输出图的实际数值分布：如果数值存在但整体偏低，说明是对比度问题而非预处理失败，通过后期增强即可挽救；如果数值全是零，则说明预处理器确实没有产出有效结果，需要回到版本排查环节。
四、其他常见踩坑点与验证方法
除了版本和分辨率，还有几个细节值得检查。一是预处理器的类型必须和ControlNet模型匹配，例如选了Canny预处理器却加载了OpenPose模型，输出无法被正确解析，预览也可能异常。二是显存不足时，某些预处理器会静默失败，可以在启动参数中开启--lowvram或者关闭其他占用显存的功能后再试。三是检查WebUI的主题或预览渲染设置，极少数情况下预览窗口本身显示有问题，可以把预处理图保存到本地再用图片查看器打开确认。
（本段用于说明：上文为完整内容，实际输出请以分隔符内为准。）
ControlNet预处理图全黑预处理器Inspector修改时间：2026-09-01 15:10:38