先判断失败发生在哪个阶段

Stable Diffusion WebUI 是常见的 AI 绘画工具。本地部署时需要 Python、Git、显卡驱动、PyTorch、模型文件和 WebUI 主程序协同工作。

安装失败并不一定是程序本身有问题。更多时候，是环境版本不匹配、依赖下载中断、路径含特殊字符、显存不足或升级后扩展冲突导致。

排查时不要反复重装。先确认失败发生在以下哪一步：拉取代码、创建虚拟环境、安装依赖、加载模型、启动浏览器界面。

Windows 用户通常从 webui-user.bat 启动。Linux 或 macOS 用户多从 webui.sh 启动。

启动窗口里的英文输出是最重要的线索。最后 20 到 50 行往往能直接指向问题。建议先复制完整报错，保存到文本文件。再按关键词检索，例如：Python、torch、CUDA、No module、out of memory、model not found、permission denied 等。

安装前的环境检查

Python 版本

多数 WebUI 分支推荐使用 Python 3.10.x。过高版本可能导致部分依赖没有兼容包，过低版本又可能不支持新组件。

安装后在命令行输入 python --version 或 py --version 查看版本。如果系统里有多个 Python，要确认 webui-user.bat 调用的是正确版本。

显卡和驱动

NVIDIA 显卡用户需要确认驱动较新，并且 PyTorch 能识别 CUDA。启动日志里若出现 Torch is not able to use GPU、CUDA unavailable，通常表示 PyTorch 版本、驱动或安装命令不匹配。

没有独立显卡也可以尝试 CPU 模式，但速度会明显下降，部分大模型体验较差。

路径设置

安装目录尽量使用纯英文和数字，例如 D:AIsd-webui。避免中文、空格和过长路径。

模型文件也建议放在 stable-diffusion-webuimodelsStable-diffusion 目录下，文件名保持简洁。路径问题会造成脚本找不到文件、权限不足或依赖编译失败。

常见报错与处理方法

Python 未找到

出现 Python was not found、No Python at 之类提示，说明系统找不到可用 Python。处理方式：安装 Python 3.10.x，并勾选 Add Python to PATH。

已安装多个版本时，可在 webui-user.bat 中设置 PYTHON=python 的实际路径，避免调用错误版本。

模块缺失

出现 No module named xxx，表示依赖没有装全。可以先关闭启动窗口，删除项目目录中的 venv 文件夹，再重新运行启动脚本，让 WebUI 重新创建虚拟环境并安装依赖。

不要随意在系统全局环境里混装依赖，否则后续更难定位。

依赖下载失败

如果卡在 Installing torch、Installing requirements 或下载依赖失败，多半是网络连接不稳定或软件源响应慢。可以稍后重试，或使用可靠的软件源镜像。

企业或校园环境中若有限制，需要确认命令行程序能访问依赖仓库。不要从不明压缩包直接替换核心依赖，容易引入版本混乱和安全风险。

显存不足

出现 CUDA out of memory、RuntimeError: out of memory，说明显存不足。可在启动参数中加入 --medvram 或 --lowvram，降低分辨率、减少批量数量，关闭高耗显存扩展。

首次测试建议使用 512×512、batch size 1，确认能稳定出图后再逐步提高设置。

模型未找到

报错提示 model not found、checkpoint not found，需要检查模型文件是否放在正确目录。后缀通常为 .safetensors 或 .ckpt。

推荐优先使用 .safetensors 格式，来源要可靠。模型下载不完整也会导致加载失败，可对比文件大小，必要时重新获取。

浏览器无法打开

启动后浏览器打不开界面，但命令行显示 Running on local URL: http://127.0.0.1:7860，说明服务已启动，只是浏览器未自动打开。可手动复制地址访问。

若端口被占用，可在启动参数里加入 --port 7861 更换端口。

如何阅读日志并定位根因

日志排错的关键是不要只看第一行红字，而要看 Traceback 的最后几行。最后一行通常是错误类型，例如 ModuleNotFoundError、RuntimeError、FileNotFoundError、ImportError。

倒数几行会显示触发错误的文件和函数。先判断是环境问题、依赖问题、模型问题还是扩展问题，再采取对应动作。

建议建立一个简单记录：

• 安装日期
• WebUI 版本
• Python 版本
• 显卡型号
• 驱动版本
• 启动参数
• 最近新增的扩展和模型

很多问题并不是当天安装导致，而是更新扩展、替换模型或修改参数后才出现。有记录时，回退会更快。

升级前必须做的备份

升级 WebUI 前，至少备份四类内容：

• models 目录中的模型文件
• outputs 目录中的历史作品
• embeddings 与 lora 等自定义资源
• webui-user.bat 或 webui-user.sh 中的启动参数

extensions 目录也建议备份清单，尤其是工作流依赖较多的用户。

如果是通过 Git 安装，升级通常在项目目录执行 git pull。升级后首次启动会自动更新部分依赖，时间可能较长。

若升级后报错，先禁用扩展测试基础功能。可以临时把 extensions 文件夹改名，或逐个移出最近更新的扩展，确认主程序是否能正常启动。

回滚方案：先回程序，再回依赖

回滚的目标是恢复到“曾经可用”的状态。如果使用 Git，可先执行 git log --oneline 查看提交记录，找到旧版本提交号后执行 git checkout 提交号。

回到旧代码后，建议删除 venv 文件夹再重新启动，让依赖与旧版本重新匹配。若只回代码不回依赖，仍可能继续报错。

如果没有使用 Git，而是下载压缩包安装，回滚只能依赖之前的完整备份。建议以后保留一个稳定版目录，例如 sd-webui-stable，另建一个测试版目录用于升级体验。不要在唯一工作目录里频繁尝试新扩展和实验分支。

扩展也需要单独回滚。很多安装失败其实由扩展引发，表现为 WebUI 主界面无法启动、某个面板加载失败或依赖冲突。

处理时先禁用全部扩展，再一次只恢复一个扩展，启动成功后再恢复下一个。这样比一次性重装更省时间。

安全边界与使用建议

本地部署时不要随便开启远程访问参数。若确需局域网内访问，应设置强口令并限制可信设备，不要把服务地址公开到不受控环境。

WebUI 可以执行扩展脚本，不明来源扩展可能读取本地文件或修改环境。安装前应查看项目维护情况、更新时间和用户反馈。

模型、插件和启动脚本都应来自可信渠道。遇到“整合包”时要格外谨慎，尤其是内含陌生可执行文件、要求关闭安全软件或要求替换系统组件的版本。

更稳妥的做法是使用官方仓库加手动安装依赖。虽然步骤多一些，但问题更容易追踪。

常见问题简答

问：重装能解决所有安装失败吗？
答：不一定。若问题来自显卡驱动、Python 版本或网络连接，重装 WebUI 仍会失败。应先看日志定位。

问：可以直接删除 venv 吗？
答：可以。venv 是项目虚拟环境，删除后下次启动会重建，但会重新下载依赖，耗时较长。模型和作品通常不在 venv 中，但操作前仍建议确认目录。

问：升级后出图变慢怎么办？
答：检查是否更换了 PyTorch、启用了新优化项或新增了高耗资源扩展。可先用默认参数测试，再逐项恢复原设置。

问：什么时候该回滚？
答：当升级后基础启动失败、关键扩展不兼容、出图结果异常且短时间无法修复时，应优先回滚到稳定版本，避免影响日常使用。

稳定运行的核心原则是：环境固定、升级留备份、日志先保存、扩展逐个排查。只要按阶段定位，大多数 Stable Diffusion WebUI 安装失败都能在不重装系统的情况下解决。