Stable Diffusion WebUI Windows 部署与常见报错解决方案

1. UnboundLocalError: local variable 'sys' referenced before assignment

原因：手动修改代码时破坏了 sys 模块作用域。

解决：还原 modules/launch_utils.py 为官方原版。

2. SyntaxError: name 'sys' is used prior to global declaration

原因：错误添加 global sys 导致语法冲突。

解决：删除所有 global sys 语句。

3. fatal: not a git repository + Couldn't fetch Stable Diffusion

原因：repositories/stable-diffusion-stability-ai 目录无效。

解决：

git clone https://github.com/Stability-AI/stablediffusion.git repositories/stable-diffusion-stability-ai
git -C repositories/stable-diffusion-stability-ai checkout cf1d67a6fd5ea1aa600c4df58e5b47da45f6bdbf

4. ModuleNotFoundError: No module named 'clip'

原因：pip 的 clip 包不是 OpenAI 官方 CLIP。

解决：

pip install https://github.com/openai/CLIP/archive/d50d76daa670286dd6cacf3bcd80b5e4823fc8e1.zip

5. ModuleNotFoundError: No module named 'sgm'

原因：缺少 SDXL 核心仓库。

解决：

git clone https://github.com/Stability-AI/generative-models.git repositories/generative-models

6. ModuleNotFoundError: No module named 'k_diffusion'

原因：缺少采样器仓库。

解决：

git clone https://github.com/crowsonkb/k-diffusion.git repositories/k-diffusion

7. ModuleNotFoundError: No module named 'packaging'

原因：虚拟环境缺少基础依赖。

解决：

venv\Scripts\activate
pip install packaging --upgrade

8. Failed to initialize NumPy: _ARRAY_API not found

原因：numpy 安装损坏。

解决：

pip install --force-reinstall numpy
pip install pytorch-lightning

9. AssertionError: Couldn't find Stable Diffusion

原因：--skip-install 屏蔽了仓库克隆。

解决：删除 webui-user.bat 里的 --skip-install。

10. FutureWarning: Importing from timm.models.layers

原因：timm 库版本警告，不影响运行。

解决：

pip install timm==0.9.8 --upgrade

五、最容易失败的关键点（新手必看）

1. 必须用 Python3.10，3.11/3.12 必报错
2. Git 必须安装并加入 PATH
3. 路径不能有中文、空格
4. 所有依赖必须装在 venv 虚拟环境
5. CLIP 必须装源码版，不能装 pip 的 clip
6. repositories 目录下 5 个仓库缺一不可

六、部署成功测试：中文提示词（直接复制）

正向

(最高画质，杰作，超精细细节), 写实照片，1 个女孩，微笑，窗边自然光，细腻皮肤，高清质感，8k

反向

卡通，动画，丑陋，变形，模糊，低分辨率，水印，文字，色差，失真，坏手，多余肢体

参数

• 采样器：DPM++ 2M Karras
• 步数：25
• 分辨率：512×768
• CFG：7

七、总结

Stable Diffusion WebUI 启动失败 99% 都是：

• Git 仓库缺失
• 依赖包版本不对
• CLIP 安装错误
• 虚拟环境异常
• Python 版本不兼容

本文整理了所有常见坑位，遇到任何报错，都能在本文找到答案。