| Stable Diffusion WebUI 爆显存、黑图、ControlNet 报错解决教程 AI Stack Nav｜常见问题全面解析 · 详细排查步骤 · 高效解决方案 |
| ★ 文章定位 ✓ 本文面向已经安装 Stable Diffusion WebUI（AUTOMATIC1111）但遇到生成失败、显存不足、黑图/绿图、ControlNet 报错的用户。 ✓ 排障思路不是“看到报错就重装”，而是按照日志、参数、模型、插件、环境五个层面逐步定位。 ✓ 适合 Windows 本地部署用户，也可供 Linux、macOS、云服务器用户参考。 |
本文建议先完成一次“最小化复现”：关闭多余插件，使用基础 SD1.5/SDXL 模型，分辨率设为 512×512 或 768×768，Batch size 设为 1，再逐步增加 Hires.fix、ControlNet、LoRA 等功能。这样可以快速判断问题是环境层、模型层，还是参数层。
一、常见问题类型概览
Stable Diffusion WebUI 的故障通常不是单点问题，而是显卡驱动、CUDA/Torch、WebUI 启动参数、模型路径、扩展版本共同作用的结果。排查时应先看“终端报错关键词”，再决定修复路径。
| 问题 | 常见报错关键词 | 优先检查项 | 推荐处理 |
| 爆显存 | CUDA out of memory / OOM | 分辨率、Batch、Hires.fix、ControlNet 数量 | 降低尺寸、Batch=1、开启 medvram 或 xformers |
| 黑图/绿图 | NaNs / black image / green screen | VAE、半精度、显卡兼容性 | 尝试 upcast-sampling、no-half-vae、必要时 no-half |
| ControlNet 报错 | model not found / preprocessor failed | 扩展是否启用、模型路径、预处理器依赖 | 重启、刷新模型、更新扩展、检查模型文件名 |
| 启动失败 | ModuleNotFound / ImportError / Torch not compiled | Python、venv、扩展冲突 | 先禁用扩展，再重建 venv 或回退版本 |
二、先做通用排障：不要一上来就重装
2.1 查看终端日志，而不是只看网页提示
WebUI 页面通常只显示“生成失败”或红色错误框，真正的线索在启动窗口/终端日志里。建议复制最后 30–80 行报错，重点搜索 CUDA、NaN、ControlNet、ModuleNotFound、ImportError、model not found 等关键词。
2.2 用最小参数复现
先用 512×512、20 steps、Batch size=1、关闭 Hires.fix、关闭 ControlNet、关闭 LoRA 的设置生成一张图。如果此时能正常出图，再逐项打开插件；如果仍失败，优先检查环境、主模型和启动参数。
2.3 备份关键配置
修改前建议复制备份 webui-user.bat / webui-user.sh、extensions 文件夹、config.json、models 目录结构截图。对新手来说，保留“可回滚点”比反复重装更重要。
三、爆显存怎么办？
3.1 先理解爆显存的本质
爆显存通常发生在模型加载、采样、Hires.fix 二次放大、ControlNet 预处理或多图批量生成阶段。SDXL、多个 ControlNet、高清修复、高清重绘和大 Batch 会显著提高显存峰值。
3.2 低风险修复顺序
建议按“参数减负 → 启动参数优化 → 插件减少 → 环境检查”的顺序执行，不建议直接使用最激进的全精度或重装方案。
| 步骤 | 操作 | 适用情况 | 效果 |
| 1 | 将 Batch size 改为 1 | 批量生成时 OOM | 显著降低峰值显存 |
| 2 | 降低宽高，如 1024 改 768 或 512 | SDXL / 高清图爆显存 | 最直接有效 |
| 3 | 关闭 Hires.fix 或降低放大倍率 | 二次放大阶段报错 | 降低采样后半段压力 |
| 4 | ControlNet 单元从多个减少到 1 个 | ControlNet 叠加爆显存 | 快速定位是哪个控制单元出问题 |
| 5 | 启用 –medvram 或 –lowvram | 显存较小但必须运行 | 牺牲速度换稳定 |
| 6 | 尝试 –xformers 或优化器设置 | NVIDIA 环境且版本兼容 | 提升速度并降低部分显存占用 |
| ★ 推荐启动参数示例 ✓ 6GB–8GB 显存：set COMMANDLINE_ARGS=–xformers –medvram ✓ 4GB 显存：set COMMANDLINE_ARGS=–lowvram –opt-split-attention-v1 ✓ 黑图/NaN 同时出现：先尝试 –upcast-sampling 或 –no-half-vae，不要直接堆满所有参数。 |
四、黑图、绿图、NaN 报错怎么办？
4.1 常见原因
黑图/绿图常见于半精度兼容问题、VAE 精度问题、显卡不支持某些 fp16 路径、模型合并文件异常、VAE 与主模型不匹配等场景。A1111 官方故障排查文档也建议先尝试 upcast-sampling，仍失败时再使用 full precision / no-half 等更重的方案。
4.2 推荐修复顺序
| 现象 | 优先处理 | 进阶处理 | 注意事项 |
| 生成结果全黑 | 切换 VAE / Auto / None | 添加 –no-half-vae | 不要同时更换模型、VAE、参数，否则难以定位 |
| 绿色或黑屏 | 添加 –upcast-sampling | 添加 –precision full –no-half | 全精度会明显增加显存占用 |
| NaN in VAE | 尝试 –no-half-vae | 更换 VAE 或回退模型 | disable-nan-check 只用于验证，不是根治 |
| 局部黑块/花屏 | 降低 CFG、采样步数、分辨率 | 换采样器或 VAE | 也可能是模型融合质量问题 |
五、ControlNet 报错怎么办？
5.1 判断是扩展问题、模型问题还是预处理器问题
ControlNet 的问题通常分为三类：扩展本身没有正确安装或启用；ControlNet 模型没有放在正确目录；预处理器依赖或版本与当前 WebUI 不匹配。Mikubill ControlNet 官方 README 提供的安装流程包括从 Extensions 安装、重启 WebUI、下载模型、放入正确文件夹并刷新模型列表。
| 问题表现 | 可能原因 | 解决方法 |
| ControlNet 面板不显示 | 扩展未启用、安装失败、未完全重启 | Extensions → Installed 检查启用状态，Apply and restart UI，并彻底重启终端 |
| 模型下拉为空 | 模型未放入正确目录或没有刷新 | 放入 extensions/sd-webui-controlnet/models 后点击刷新按钮 |
| 预处理失败 | 预处理器依赖损坏或版本冲突 | 先测试 Canny/Depth 基础预处理器，再更新扩展或重装依赖 |
| 模型文件报错 | 文件损坏、下载不完整、yaml 不匹配 | 重新下载模型，确保模型文件与 yaml 文件名一致 |
| 使用后爆显存 | ControlNet 单元过多或分辨率太高 | 减少 ControlNet 单元、启用 Low VRAM、降低尺寸 |
六、模型不显示、路径混乱怎么处理？
6.1 先确认模型类型
很多新手把 Checkpoint、VAE、LoRA、ControlNet 模型混放，导致模型不显示或生成异常。建议按模型类型建立固定目录，并在每次下载后记录模型来源与适配版本。
6.2 模型不显示的排查步骤
- 确认文件扩展名是否为 .safetensors、.ckpt、.pt、.pth 等正确格式。
- 确认模型没有被浏览器下载成 .tmp 或被压缩包包裹。
- 点击 WebUI 模型下拉框旁边的刷新按钮；ControlNet 也需要单独刷新。
- 仍不显示时，重启 WebUI，而不是只刷新网页。
- 检查文件路径是否含有异常字符、权限问题或中文路径兼容问题。
七、Stable Diffusion WebUI 稳定使用工作流
7.1 日常生成建议
| 阶段 | 推荐操作 | 目的 |
| 启动前 | 关闭占用显存的软件，如游戏、剪辑软件、浏览器重负载页面 | 降低显存碎片和后台占用 |
| 首次测试 | 基础模型 + 512×512 + Batch=1 + 20 steps | 确认环境是否正常 |
| 加插件 | 一次只启用一个扩展或 ControlNet 单元 | 快速定位冲突源 |
| 高清修复 | 先小图确定构图，再开启 Hires.fix | 避免反复消耗显存和时间 |
| 保存记录 | 保存 prompt、seed、模型、VAE、扩展版本 | 方便复现与排错 |
7.2 推荐提示词模板
| ★ 通用高质量出图模板 ✓ 主体：一名未来感女性工程师，站在蓝色科技实验室中 ✓ 画质：masterpiece, best quality, ultra detailed, cinematic lighting, sharp focus ✓ 构图：medium shot, symmetrical composition, depth of field ✓ 负面提示词：low quality, blurry, bad anatomy, distorted hands, watermark, text, logo |
八、安全与合规使用建议
- 不要随意下载来源不明的模型、扩展和脚本，尤其是需要执行 Python 代码的插件。
- 优先使用 .safetensors 格式模型，避免执行不可信的旧格式权重文件。
- 商用前确认模型、LoRA、素材和字体的授权范围。
- 定期备份 models、outputs、extensions、config.json 和启动脚本。
- 遇到异常先查看日志，不建议关闭安全检查或复制未知命令。
九、常见问题 FAQ
Q1：爆显存是不是只能换显卡？
不一定。先降低分辨率、Batch size、关闭 Hires.fix 和多 ControlNet，再尝试 medvram / lowvram。只有在你长期需要 SDXL 高清批量生成时，升级显卡才更划算。
Q2：黑图是不是模型坏了？
可能是模型/VAE 问题，也可能是显卡半精度兼容问题。建议先用基础模型和默认 VAE 测试，再逐步尝试 upcast-sampling、no-half-vae。
Q3：为什么 ControlNet 模型放进去还是不显示？
常见原因是路径错误、没有点击刷新、未完全重启、模型文件下载不完整，或模型文件与 yaml 文件名不一致。
Q4：disable-nan-check 能解决黑图吗？
不能。它只是关闭 NaN 检查，让程序继续跑，不能修复 VAE 或半精度问题。正式使用不建议把它当作根治方案。
Q5：WebUI 更新后插件全坏了怎么办？
先禁用所有扩展启动；能启动后逐个启用插件定位冲突。必要时回退 WebUI 或插件版本，再重建 venv。
Q6：4GB 显存还能用 Stable Diffusion WebUI 吗？
可以，但建议使用 SD1.5、512×512、Batch=1、低显存参数，并避免叠加多个 ControlNet 或高倍率 Hires.fix。
参考资料
- AUTOMATIC1111 Stable Diffusion WebUI：Command Line Arguments and Settings：https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Command-Line-Arguments-and-Settings
- AUTOMATIC1111 Stable Diffusion WebUI：Troubleshooting：https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Troubleshooting
- AUTOMATIC1111 Stable Diffusion WebUI：Optimizations：https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Optimizations
- Mikubill sd-webui-controlnet：ControlNet for Stable Diffusion WebUI：https://github.com/Mikubill/sd-webui-controlnet
AI Stack Nav｜让 AI 技术更好地为办公与创作服务。
