概述
Stable Diffusion WebUI 是目前 AI 绘画最主流的本地部署工具，但 Windows 环境下因为 Python 版本、虚拟环境、Git 仓库、依赖包、CLIP 编译等问题，90% 的新手都会启动失败。本文包含标准 Windows 一键部署流程及常见报错的解决方案。
环境准备
必备软件
- Python 3.10.11（必须 3.10，高版本必报错）
- Git（安装时勾选 Add to PATH）
- 模型文件（如 Realistic Vision V6.0）放入：
models/Stable-diffusion/
获取源码
git clone https://github.com/AUTOMATIC1111/stable-diffusion-webui.git
标准启动流程
- 进入目录
- 双击
webui-user.bat - 自动下载依赖、克隆仓库、安装 torch
- 出现
Running on local URL: http://127.0.0.1:7860成功
常见报错及解决方案
以下汇总了部署过程中常见的错误及其修复命令。
| 报错信息 | 核心原因 | 解决方案 |
|---|---|---|
| UnboundLocalError: sys 未定义 | 代码修改导致作用域异常 | 还原官方 launch_utils.py |
| SyntaxError: sys 全局声明错误 | 错误使用 global sys | 删除所有 global sys 语句 |
| fatal: not a git repository | 仓库缺失 / 不是 git 目录 | 手动克隆仓库到 repositories |
| Couldn't fetch Stable Diffusion | stable-diffusion-stability-ai 缺失 | 重新克隆指定版本仓库 |
| ModuleNotFoundError: clip | CLIP 未安装 / 安装错误 | 安装源码版 CLIP，非 pip clip |
| ModuleNotFoundError: sgm | 缺少 generative-models 仓库 | 克隆仓库 |
| ModuleNotFoundError: k_diffusion | 缺少 k-diffusion 仓库 | 克隆仓库 |
| ModuleNotFoundError: packaging | 虚拟环境缺少 packaging | pip install packaging --upgrade |
| Failed to initialize NumPy | numpy 损坏 | 强制重装 numpy |
| AssertionError: Couldn't find Stable Diffusion | 核心仓库被 --skip-install 屏蔽 | 移除 --skip-install |
| FutureWarning: timm.models.layers | timm 版本警告 | 升级 timm 到 0.9.8 |
详细修复步骤
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
关键注意事项
- 必须用 Python3.10，3.11/3.12 必报错
- Git 必须安装并加入 PATH
- 路径不能有中文、空格
- 所有依赖必须装在 venv 虚拟环境
- CLIP 必须装 源码版，不能装 pip 的 clip
repositories目录下 5 个仓库缺一不可
测试提示词示例
正向
(最高画质，杰作，超精细细节), 写实照片，1 个女孩，微笑，窗边自然光，细腻皮肤，高清质感，8k
反向
卡通，动画，丑陋，变形，模糊，低分辨率，水印，文字，色差，失真，坏手，多余肢体
参数
- 采样器：DPM++ 2M Karras
- 步数：25
- 分辨率：512×768
- CFG：7
