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

Automatic1111 是常用的 AI绘画工具 WebUI。安装过程看似只是运行启动脚本，实际会连续完成多个步骤：

• Git 检查
• Python 虚拟环境创建
• PyTorch 与依赖包安装
• 模型加载
• 扩展初始化

安装失败时，不建议反复双击启动文件碰运气。正确做法是：先确认失败停在什么位置。

是窗口一闪而过？依赖下载中断？Torch 安装失败？CUDA 不可用？模型加载报错？还是页面能打开但生成时报错？阶段不同，处理方法完全不同。

Windows 用户通常运行 webui-user.bat，Linux 或 macOS 用户通常运行 webui.sh。若窗口直接关闭，可在终端中进入目录后手动执行脚本，这样能看到完整提示。

排查时建议：

• 先不要安装第三方扩展
• 不要一次放入大量模型
• 保持最小环境启动

这样能减少干扰。

安装前环境检查

最常见的问题来自 Python 版本不匹配。Automatic1111 较稳定的组合通常是 Python 3.10.x。过新的 3.11、3.12 在部分依赖上可能出现兼容问题。

检查方式：终端输入 python --version 或 py --version。如果版本不符合要求，建议卸载多余版本，或在启动脚本中明确指定 Python 路径。

Git 也是必需组件，用于拉取项目与扩展。终端输入 git --version 能正常显示版本，才说明可用。如果提示“不是内部命令”，需要重新安装 Git，并勾选“加入系统路径”。

显卡方面，NVIDIA 用户要确认驱动较新。终端输入 nvidia-smi 能显示显卡信息。没有独立显卡也能尝试CPU模式，但速度会很慢，且部分功能不可用。

目录路径也会影响安装。建议将项目放在英文路径，例如 D:AIwebui。避免中文、特殊符号、过深目录和同步盘目录。路径中带空格一般可用，但排错时最好先排除变量。

磁盘空间至少预留 20GB 以上。依赖、缓存、模型文件会快速增长。

常见报错与处理思路

“Python was not found” 或 “No Python at ...”

说明脚本找不到正确解释器。处理方式：安装 Python 3.10，并勾选 “Add Python to PATH”。若电脑里有多个版本，可编辑 webui-user.bat，在 set PYTHON= 后写入 python.exe 的完整路径。

“git is not recognized”

说明 Git 没有加入环境变量。重新安装 Git 后，关闭所有终端，再重新打开执行脚本。若项目下载不完整，建议删除残缺目录后重新获取，不要在半截文件夹中继续安装。

“No module named launch” 或 “No module named modules”

多半是目录结构不完整，或启动脚本不在项目根目录执行。确认目录下应有 launch.py、webui.py、modules 等文件夹。通过压缩包下载项目时，注意不要多套一层目录。

卡在 installing torch 或 依赖下载超时

通常是网络连接不稳定、pip 源响应慢或缓存损坏。可先删除 venv 文件夹，让脚本重建虚拟环境。也可在终端中升级 pip：python -m pip install -U pip。使用镜像源时要选择可信来源，避免混用太多源，防止包版本混乱。

“Torch is not able to use GPU” 或启动后只能用 CPU

通常与显卡驱动、CUDA 版 PyTorch 或启动参数有关。Automatic1111 不要求单独安装完整 CUDA 工具包，但显卡驱动必须支持对应运行库。可先更新显卡驱动，再删除 venv 重装依赖。

低显存显卡可在 webui-user.bat 的 COMMANDLINE_ARGS 中加入 --medvram 或 --lowvram，降低显存占用。

日志应该看哪里

排错最重要的就是保留完整日志。Windows 下直接双击脚本容易错过信息，推荐按住 Shift 在项目目录打开终端，再执行 webui-user.bat。Linux 或 macOS 可执行 ./webui.sh，并把终端输出保存下来。

关键不是只看最后一行。应从第一处 ERROR、Traceback、RuntimeError 往上读，通常真正原因在前面几行。

如果启动到一半失败，项目目录内可能已有 venv、repositories、tmp、extensions 等文件夹。排查时可以按顺序处理：

• 先禁用扩展
• 再重建依赖
• 最后重拉项目

不要一上来就全盘删除。

遇到页面能打开但生成失败，可查看终端实时输出。若是模型报错，常见原因是：模型文件损坏、格式不支持、文件未完整下载或放错目录。基础模型通常放在 models/Stable-diffusion，VAE 放在 models/VAE，LoRA 放在 models/Lora。文件名可以改，但扩展名和目录要正确。

推荐的排查步骤

1. 确认系统、显卡、Python、Git。记录 python --version、git --version、nvidia-smi 的结果。
2. 使用英文短路径重新放置项目。
3. 暂时移走 extensions 目录中的第三方扩展，只保留原始项目启动。
4. 删除 venv 文件夹，让脚本自动重建依赖。
5. 如仍失败，再考虑重新获取项目文件。

如果你曾修改过 webui-user.bat 或启动参数，建议先备份后恢复默认。常见参数包括 --xformers、--medvram、--lowvram、--listen、--port 等。

注意：--xformers 并非所有环境都稳定，安装失败时应先去掉它，确认基础功能正常后再尝试。端口冲突时可改为 --port 7861；如果页面打不开，先检查终端是否显示 Running on local URL。

对于 macOS 用户，需注意芯片架构与依赖兼容。Apple Silicon 设备一般不走 CUDA 路线，启动参数和性能表现与 NVIDIA 显卡不同。Linux 用户则要留意 Python 虚拟环境权限，避免用管理员权限安装后又用普通用户启动，导致文件读写异常。

升级前一定要备份

Automatic1111 更新频繁。升级能获得新功能与修复，但也可能引入扩展不兼容、依赖变化、参数失效等问题。升级前建议备份三类内容：

• webui-user.bat 或 webui-user.sh 中的启动参数
• extensions 扩展目录
• config.json、ui-config.json、styles.csv 等配置文件

模型文件体积大，不必每次复制，但要确认没有和项目放在同一待删除目录中。

常规升级可在项目目录执行 git pull，然后重新运行启动脚本。若升级后依赖异常，先删除 venv 重建。若升级后只有某个扩展出问题，可先把该扩展移出 extensions，再逐个放回测试。

建议：不要同时更新主程序、所有扩展和依赖，否则出错后很难判断来源。

回滚方案怎么做

如果升级后无法使用，而之前版本正常，可以通过 Git 回到旧版本。先在项目目录执行 git log --oneline，找到之前可用的提交编号，再执行 git checkout 提交编号。回滚后建议删除 venv，让依赖重新匹配当前代码。若要回到最新版本，可执行 git checkout master 或对应主分支名称，再 git pull。

更稳妥的做法是在升级前记录当前版本号：git rev-parse --short HEAD。也可以直接复制一份完整项目目录作为备份，命名为 webui_backup_日期。这样即使升级失败，也能快速切回旧目录继续使用。

对生产用途或固定工作流用户，建议不要追最新版本，而是使用经过验证的稳定版本。

常见问题简答

• 问：安装时反复下载同一个依赖怎么办？ 答：通常是上次安装中断或缓存异常，可删除 venv 后重试；如果仍失败，检查 pip 源、磁盘空间和权限。
• 问：启动成功但生成图片很慢怎么办？ 答：确认是否使用了 GPU。低显存设备可降低分辨率、批次数和采样步数，并使用 --medvram。不要同时加载过多扩展和大型模型。
• 问：扩展安装后打不开页面怎么办？ 答：先把新装扩展从 extensions 移走，确认主程序可启动，再查看该扩展说明是否要求特定版本。扩展越多，冲突概率越高。
• 问：能不能直接删除重装？ 答：可以，但要先备份 models、outputs、embeddings、extensions、配置文件和启动脚本。很多用户重装后找不到旧模型和预设，就是因为没有区分程序目录与数据目录。

安全边界与实用建议

AI绘画工具本身只是创作软件。安装时应坚持来源可信、步骤可复现、权限最小化。不要运行来历不明的整合包脚本，不要随意关闭系统防护，不要把私人文件夹暴露给不熟悉的扩展。

扩展安装前应查看更新时间、说明文档和问题反馈。长期无人维护的扩展要谨慎使用。

排错时养成三点习惯：

• 每次只改一个变量
• 保留完整报错
• 重要文件先备份

大多数 Automatic1111 安装失败都不是“电脑不支持”，而是版本、依赖、路径或扩展冲突。按环境检查、日志定位、最小化启动、逐步恢复的顺序处理，通常可以在较短时间内找到原因，并建立一套稳定可维护的本地 AI绘画环境。