1. 报错先分类：把问题定位在四层链路上

Stable Diffusion 这套东西最让人头疼的地方，不是它难，而是它报错的时候往往只给你一句“RuntimeError”或者一串几十行的 Python 堆栈，看起来什么都说了，实际上什么都没说。我从最开始用一张 8GB 显存的卡跑 512×512，到后来折腾多模型、多插件、批量出图，这些年攒下来的报错截图能塞满一个文件夹。慢慢发现一个规律：绝大多数报错并不需要逐行读堆栈，只要先判断它落在哪一层，排查范围立刻能缩小一大半。这篇内容就是我自己的报错笔记整理，偏向“遇到问题怎么快速动手”,而不是讲模型原理。刚入门的新手可以照着顺序排，已经跑了一段时间、开始折腾插件和多模型的老手，也能从中找到几类反复出现但容易被误判的坑。全文围绕模型加载、显存不足、依赖冲突、生成阶段异常这几条主线展开，每一条都给到可执行的命令、参数和判断依据。

1.1 环境层、模型层、计算层、插件层

我把 Stable Diffusion 的运行链路粗分成四层，报错基本都能归到其中一层。环境层是 Python、PyTorch、CUDA 驱动、xformers 这些底层依赖，它的典型症状是启动就崩、导入模块失败、版本号对不上。模型层是权重文件、配置文件、VAE、LoRA、ControlNet 模型，它的典型症状是加载到一半停住、提示 key 不匹配、文件大小不对。计算层是显存、精度、分辨率、批大小这些运行时资源，典型症状是跑到一半 OOM、出黑图、出花图。插件层是各种扩展脚本和它们的依赖，典型症状是启动时某个扩展加载失败、界面按钮消失、控制台刷红色报错。

分层的好处很直接：同样是“启动失败”,环境层要去看 Python 版本和 torch 版本，模型层要去核对文件完整性，插件层要去看扩展目录里的报错。如果一上来就盲目重装，很可能把原本没问题的环境搞乱，反而增加变量。我的习惯是先在脑子里过一遍：这个报错是启动阶段出现的，还是点“生成”之后出现的？启动阶段优先查环境和插件，生成阶段优先查模型和显存。这个判断只需要几秒钟，但能省掉大量试错。

提示：排查期间尽量不要同时改两个变量。比如既升级了 torch 又换了模型，最后报错消失了，你也不知道是哪个动作起的作用，下次遇到同样问题还是不会。

1.2 读堆栈的三个习惯

第一，从下往上看，但只看最后五行。Python 的堆栈是调用链，最底下那行才是真正抛异常的位置，上面大多是框架内部的调用。第二，抓关键词而不是读全文。像CUDA out of memory、KeyError、size mismatch、No module named、half、NaN这些词，基本一眼就能定性。第三，保留完整日志。控制台里被刷掉的那几行往往才是根因，尤其是插件加载阶段的 warning，后面生成时爆的错经常是它引起的。

我见过不少人把报错截图发出来，只截了最上面一行“Error”,下面的关键信息全被裁掉了，这种基本没法判断。养成把控制台输出重定向到文件的习惯，回头翻的时候省事很多。

# 启动时把标准输出和错误输出同时写入日志文件 python launch.py --listen --port 7860 > run.log 2>&1

出问题后直接搜run.log里的Error、Traceback、OOM,比在终端里来回翻页靠谱得多。

2. 模型加载类报错：从权重文件到配置的排查顺序

模型加载失败是新手遇到的第一道坎，也是最容易误判的一类。很多人看到“加载失败”第一反应是软件坏了，实际上八成以上是文件本身的问题：下载中断、后缀被浏览器改掉、放错目录、配套的配置文件缺失。这一节按“文件是否完整、格式是否匹配、目录是否正确”三步走，基本能覆盖常见的加载类报错。

2.1 权重文件损坏与下载不完整

最典型的症状是加载进度条走到某个百分比卡死，或者直接抛出反序列化错误。原因是下载过程中连接中断，文件只写了一半，但文件名看起来是完整的。判断方法很简单，比对文件大小。一个常规的 SD1.5 底模大约 2GB 到 4GB，SDXL 底模通常在 6GB 以上，如果看到只有几百 MB 的“大模型”,那基本可以确定是残包。

更稳妥的做法是校验哈希值。发布方一般会给出 SHA256，本地算一遍对一下，一致才说明文件没问题。

# Linux / macOS 计算 SHA256 shasum -a 256 model.safetensors # Windows PowerShell Get-FileHash .\model.safetensors -Algorithm SHA256

没有哈希值可对的时候，我一般看两个地方：文件大小是否落在合理区间，以及用加载库试着读一下头部信息。safetensors 格式的头部是明文 JSON，读起来很快，能立刻判断文件结构是否完整。

from safetensors import safe_open path = "model.safetensors" try: with safe_open(path, framework="pt", device="cpu") as f: keys = list(f.keys()) print("tensor 数量:", len(keys)) print("前五个 key:", keys[:5]) except Exception as e: print("文件读取失败:", repr(e))

如果这一步就报错，不用再往下折腾了，重新下载是唯一解。顺带说一句，下载工具尽量用支持断点续传的，别用浏览器直接下大文件，中断概率高很多。

2.2 safetensors 与 ckpt 的加载差异

.ckpt本质是 pickle 序列化，加载时会执行反序列化逻辑，所以它对环境更敏感，遇到不认识的类就会抛ModuleNotFoundError或者UnpicklingError。.safetensors只存张量和元数据，不涉及代码执行，加载更稳，也更安全。现在新模型基本都发 safetensors，但老模型和老教程里 ckpt 依然常见。

我遇到过的典型报错是 ckpt 加载时提示找不到某个模块，这种情况通常不是文件坏了，而是模型训练时依赖了某个自定义层，加载环境里没有。解决办法有两个：一是找同模型的 safetensors 版本，二是补上对应依赖。前者更省事，我一般优先选前者。

另一个容易被忽略的点是精度标记。有些 ckpt 内部存的是 fp16，有些是 fp32，加载时如果强制指定了不匹配的精度，会出现数值异常而不是直接报错，表现为出图发灰、发黑。这种情况用--no-half启动一次做对比，能快速确认是不是精度问题。

2.3 模型目录与配置文件命名

目录放错是特别隐蔽的一类问题。软件不会提示“你放错文件夹了”,而是根本不显示这个模型，或者在切换时报KeyError。我的做法是固定一套目录结构，每次放模型前先确认路径。底模放主模型目录，VAE 单独一个目录，LoRA 和 ControlNet 各自独立，不要混在一起。

配置文件也常被忽略。部分模型需要同名的.yaml,里面记录了模型结构参数。只拷了权重没拷配置，加载时就会提示缺少配置或者结构不匹配。判断方法是看发布页有没有附带 yaml 文件，有就一起下，放在同一目录、保持同名。

还有一种情况是文件名里带了空格、中文或者特殊符号，某些插件在拼接路径时会解析失败。这类问题排查起来很费时间，因为报错信息往往指向别处。我的经验是模型文件名统一用英文、数字、下划线，长度别太长，能避开一大票莫名其妙的路径问题。

注意：改名之后记得同步更新引用该模型的工作流或配置，否则会出现“文件明明在，却提示找不到”的矛盾现象。

3. 显存不足：量化计算与参数取舍

CUDA out of memory大概是出现频率最高的一条报错。它的麻烦之处在于，同样的参数，昨天能跑今天不能跑，或者换了个插件就爆了。原因不复杂：显存是动态分配的，模型权重、激活值、注意力计算的中间结果、图像解码缓冲，全都在抢同一块空间。想稳住，得先知道显存被谁吃了，再做有针对性的减法，而不是一上来就把分辨率砍半。

3.1 显存到底被谁吃了

粗略拆一下，生成一张图时的显存占用主要来自四块。模型权重是常驻的，SD1.5 的 fp16 权重约 2GB，SDXL 大约 5GB 到 7GB。文本编码器在处理提示词时会额外占用，提示词越长、token 越多，占用越高。注意力计算的中间激活跟分辨率和批大小强相关，是波动最大的一块。VAE 解码在最后一步把潜变量还原成像素图，高分辨率下这一下子能吃掉不少显存，很多人是在“进度条 100% 之后”才爆的，就是卡在这里。

所以看到 OOM 先别急着降分辨率，先看它是在哪个阶段爆的。采样中途爆，多半是分辨率或批大小问题；最后一步爆，优先考虑 VAE 分块解码；一加载模型就爆，那是权重本身太大，得换精度或者换模型。

3.2 分辨率、批大小与显存的粗略关系

显存占用和像素数大致成平方关系，分辨率翻倍，占用接近四倍。批大小基本是线性叠加。可以拿一个基准值做参照：在 8GB 显存、SD1.5、fp16 的条件下，512×512 单张通常比较稳，768×768 就开始紧张，1024×1024 基本要靠额外优化。SDXL 的门槛更高，1024×1024 在 12GB 以上会舒服很多。

这张表是经验值，实际还受驱动版本、是否启用注意力优化、插件数量影响。我一般建议先用一组“确定能跑”的参数把流程跑通，再一步步往上加，而不是直接照抄别人的高分辨率参数。

3.3 减显存的实操组合拳

减显存的手段不少，但要按代价从低到高排。第一档是零画质损失或极小损失：启用分块 VAE 解码、开启注意力优化、把不必要的插件临时关掉。第二档是有轻微影响：降低批大小、降低分辨率后再放大、减少同时挂载的 ControlNet 数量。第三档是明显影响：启用低显存模式、强制半精度、切到更小的模型。

启动参数里几个常用的：

# 启用分块 VAE 解码，缓解最后一步 OOM python launch.py --medvram --opt-split-attention-v1 # 显存特别紧张时的低显存模式 python launch.py --lowvram # 禁用半精度 VAE，解决部分模型的黑图问题 python launch.py --no-half-vae

--medvram和--lowvram的原理是把部分模块在需要时才移到显存，用完再挪走，代价是速度下降。--lowvram更激进，速度损失明显，非必要不用。注意力优化方面，能装 xformers 就装，装不上就用内置的 split attention，效果差一些但稳定。

还有一个常被忽略的点：同时挂多个 ControlNet 是显存杀手。每多一个 ControlNet，就多一份模型权重和一份中间特征图。我见过有人挂了五六个 ControlNet 然后抱怨 12GB 不够用，这种情况先减到一两个，问题往往就没了。

提示：调参时一次只改一个变量，并且记录下“能跑通”的那组参数。我自己的习惯是在笔记里存一份 baseline 配置，以后遇到 OOM 直接回退到 baseline 再逐项加。

4. 依赖与版本冲突：Torch、CUDA、xformers 三件套

环境问题是最折磨人的，因为它不按常理出牌：同样的安装步骤，在别人机器上一把过，在你这里就卡在某个轮子上。核心原因是这三者的版本必须互相咬合，任何一个错位都会在导入阶段或第一次调用 GPU 时炸掉。这一节讲清楚对应关系、安装顺序和冲突排查。

4.1 版本对应关系与查询方法

先明确一个概念：显卡驱动支持的最高 CUDA 版本，和你实际安装的 CUDA 运行时版本，是两回事。PyTorch 的预编译包自带 CUDA 运行时，所以大多数情况下你不需要单独装完整的 CUDA 工具包，只要驱动够新就行。查询驱动支持的版本：

nvidia-smi

输出右上角会显示类似CUDA Version: 12.x的字样，这是驱动支持的最高版本，不是已安装版本。再查实际安装的 torch 和它编译时用的 CUDA：

import torch print("torch:", torch.__version__) print("torch 编译 CUDA:", torch.version.cuda) print("CUDA 是否可用:", torch.cuda.is_available()) print("设备数量:", torch.cuda.device_count())

如果is_available()返回 False，先别怀疑显卡坏了，八成是 torch 装成了 CPU 版本。这种情况在 pip 安装时很常见，因为默认源可能给的是 CPU 轮子。解决办法是显式指定带 CUDA 的索引地址重装。

4.2 安装顺序与环境隔离

我踩过最大的坑是“在系统 Python 里反复装卸”。装到第三遍的时候，残留的半截包会把新装的覆盖掉，报错越来越离谱。后来固定用虚拟环境，一个项目一个环境，出问题直接删掉重建，成本极低。

# 创建并激活虚拟环境 python -m venv sd_env source sd_env/bin/activate # Linux / macOS sd_env\Scripts\activate # Windows # 先装匹配的 torch，再装其余依赖 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 pip install -r requirements.txt

顺序很重要：先 torch，后其他。因为很多包在安装时会检测 torch 版本，如果 torch 还没装，它们可能拉一个不匹配的版本进来，导致后面出现难以解释的符号错误。xformers 放在 torch 之后装，并且它的版本必须和 torch 版本严格对应，装错的表现通常是导入时报undefined symbol。

4.3 插件依赖冲突的定位

插件层的报错有个特点：它往往不影响主程序启动，只在用到该插件时才炸，或者干脆在启动时静默失败，界面上少一个面板。定位方法是看启动日志里每个扩展的加载结果，找到标红或标Failed的那一行，再进到对应目录看它的依赖文件。

常见冲突是同一个包的不同版本要求。A 插件要gradio 3.x,B 插件要gradio 4.x,装哪个都会让另一个不舒服。我的处理原则是：主程序能跑优先,冲突插件如果非必需就先停用，把它的目录改名加个下划线前缀，主程序就不会加载它。确实需要的话，再单独找兼容版本，而不是硬升级把整个环境搞崩。

# 临时停用某个扩展：目录名前加下划线 mv extensions/some-extension extensions/_some-extension

这个动作看着土，但特别有效，而且可逆，排查问题时比卸载重装安全得多。

5. 采样与生成阶段的疑难杂症

环境通了、模型能加载、显存也够，剩下的问题就集中在“出图不对”上。这一类最难受，因为它不报错，只是结果不对：全黑、全灰、噪点、扭曲、颜色诡异。排查思路和前面不同，得从 VAE、精度、采样器、提示词长度这几个方向逐个排除。

5.1 黑图、灰图与纯色图的成因

全黑图最常见的原因是 VAE 数值溢出。fp16 精度下，某些 VAE 在解码时会出现 NaN，最终输出全黑。解决办法是启用--no-half-vae,让 VAE 用 fp32 跑，速度略降但基本能解决。如果加了参数还是黑，那要怀疑模型本身和 VAE 不匹配，比如用了 SDXL 的 VAE 去解 SD1.5 的潜变量，这种情况换回配套 VAE 即可。

全灰图或者低对比度的图，很多时候是提示词权重和采样步数不匹配，步数太少模型还没收敛。先把步数提到 25 到 30 试一次，如果明显改善，说明就是步数问题。还有一种情况是 CFG 值设得过高，画面会发硬、发灰，适当降到 7 左右对比一下。

噪点图则要看采样器和调度器的搭配。有些采样器需要特定的调度器配合，选错了会出满屏噪点或者糊成一团。我的做法是先用一组公认稳定的组合跑基准图，确认基础没问题，再去试新采样器。

5.2 VAE 相关的报错与色彩异常

VAE 报错通常长这样：Error while deserializing VAE或者size mismatch for vae。前者是文件问题，后者是架构不匹配。判断方法很简单，看 VAE 是给哪个模型用的，SD1.5 和 SDXL 的 VAE 不能混用，混用不一定报错，但出图颜色会明显偏，比如发绿、发紫。

色彩异常还有一个隐蔽原因：VAE 精度。同一张图，用 fp16 VAE 和 fp32 VAE 解码，颜色可能有肉眼可见的差异，尤其在暗部。如果你发现出图整体偏灰、暗部死黑，可以试试切换 VAE 精度做对比。

# 强制 VAE 使用 fp32，排查黑图和偏色 python launch.py --no-half-vae

注意：换 VAE 之后记得清一次缓存或者重启，部分界面会缓存上一次的 VAE，导致你以为换了其实没生效。

5.3 LoRA 与 ControlNet 加载失败

LoRA 报错常见的是size mismatch和key not found。前者通常是 LoRA 训练时用的底模和你现在用的底模架构不一致，比如拿 SDXL 的 LoRA 往 SD1.5 上挂。后者多半是文件损坏或者只下了一部分。判断时先看文件大小，常规 LoRA 几十 MB 到几百 MB，明显偏小就是残包。

ControlNet 的问题更多出在预处理和后处理上。报错提示找不到预处理器，一般是扩展没装全或者版本不匹配；提示张量维度不对，往往是输入图和模型要求的尺寸或通道数不一致。我的习惯是先用一张标准尺寸的图跑通流程，确认模型和预处理器都能工作，再换自己的图，这样能把“图的问题”和“环境的问题”分开。

6. 常见问题速查与排查流程

前面几节是按层拆开讲的，实际遇到问题时往往是混在一起。这一节给一张速查表和一套排查顺序，方便在紧张的时候照着走，不用重新推理。

6.1 高频报错速查表

6.2 一套可复用的排查顺序

我的固定顺序是：先看报错发生在哪个阶段，再确认最近改了什么，最后才动手。启动阶段出错，优先怀疑环境和插件，动作是看日志、停用最近加的扩展、核对版本。加载阶段出错，优先怀疑文件，动作是校验大小和哈希、确认目录和命名。生成阶段出错，优先怀疑资源和精度，动作是回退到 baseline 参数、逐个加回去。

这个顺序的核心是“缩小变量”。很多人一出错就把能改的都改一遍，结果问题没了也不知道为什么没的，下次照样抓瞎。反过来，每次只动一个地方，虽然慢一点，但经验是能沉淀下来的。

还有一个特别实用的习惯：给每个能跑通的环境做一次快照。虚拟环境可以导出依赖列表，配置文件可以备份一份，模型目录可以记下版本。真出问题时，回滚比排查快得多。

# 导出当前环境的依赖清单，出问题时方便对照 pip freeze > requirements.lock

这份清单在换机器或者重装时特别有用，能避免“明明装的是同一个包，行为却不一样”的困惑。

7. 我个人踩坑后留下的几条经验

最后说几条不太像“技术要点”、但确实帮我省了大量时间的经验。第一，报错先别搜,先复现。很多报错是偶发的，重启一次就没了，急着去搜反而会被带到不相关的方向。第二，日志比截图有用。控制台里的 warning 往往是后面报错的伏笔，养成留日志的习惯。第三，模型和插件要“少而精”。我有一段时间装了十几个扩展，结果每次启动都在排查哪个扩展又崩了，后来精简到常用的几个，稳定性肉眼可见地提升。第四，参数要留 baseline。一组确定能跑通的分辨率、步数、CFG、采样器组合，遇到问题先回退，再逐项加，比从头试快得多。第五，显存不够时优先改流程，而不是硬堆硬件。先降分辨率再放大、先单张再批量、先关插件再谈优化，很多“必须换卡”的场景其实换个流程就过去了。

这套东西没有什么高深原理，都是被报错逼出来的条件反射。真要说心得，就是别怕报错，把每一次报错当成一次缩小未知范围的机会，记下来，下次就能少花一半时间。