Stable Diffusion WebUI 的插件生态依赖 Git 从远端仓库拉取代码，安装或更新插件时，WebUI 会在后台执行 git clone 和 git pull。一旦网络到 GitHub 不稳定、代理规则遗漏终端或本地仓库缓存损坏，安装流程就会卡在拉取阶段，界面只显示一串红字。要解决这个问题，不能只看 WebUI 的提示，需要回到命令行确认 git 的具体报错。
先判断 git pull 到底卡在哪
遇到安装失败，第一步是打开 WebUI 启动时使用的终端窗口。如果通过一键包或整合包启动，通常会有控制台输出。找到类似 fatal: unable to access 或者 error: RPC failed 的信息，这条信息决定了后续处理方向。
常见的 connection timed out 或 Failed to connect to github.com port 443 通常是网络访问不到 GitHub。此时浏览器能打开网页不代表终端能正常 git，因为浏览器可能走了系统代理，而 git 没有读取到代理配置。另一种情况是 RPC failed、curl 56 Recv failure 或 early EOF，说明连接建立了但传输过程中被切断，常见于大仓库或网络抖动。还有 cannot lock ref、reference broken 等提示，多半是本地 .git 目录已经损坏，继续 pull 只会重复报错。
也有少部分报错和网络无关，比如 fatal: not a git repository，表示当前目录不是有效的 Git 仓库。这个情况在手动解压插件后尝试 git pull 时很常见，后文会说明原因和处理方式。
手动下载插件 zip 并放入 extensions
当 git 拉取始终失败时，最直接的替代方案是绕过 git clone 和 git pull，手动下载插件代码。打开插件仓库的 GitHub 页面，点击 Code 按钮，选择 Download ZIP 即可获得压缩包。如果 GitHub 页面打开慢，可以在仓库地址前加镜像前缀，例如将 github.com 替换为常见的加速服务地址。下载得到的 zip 文件名通常带有 -main 或 -master 后缀。
解压后需要把文件夹放到 Stable Diffusion WebUI 的 extensions 目录下。注意目录层级有严格要求：解压后的文件夹里应该能直接看到 scripts、install.py 或 requirements.txt 等文件，不能出现 extensions/插件名/插件名-main/scripts 这种嵌套。如果多了一层，Windows 用户可以直接把里层文件夹剪切出来。
# 假设下载到 ~/Downloads/sd-webui-controlnet-main.zip cd ~/Downloads unzip sd-webui-controlnet-main.zip -d /path/to/stable-diffusion-webui/extensions/ # 检查目录结构，确保 requirements.txt 和 scripts 在同一层 ls /path/to/stable-diffusion-webui/extensions/sd-webui-controlnet-main
放入目录后不要急着启动。部分插件除了 Python 代码，还依赖额外的 pip 包。需要进入插件目录，安装 requirements.txt 中列出的依赖。WebUI 通常自带虚拟环境，Windows 下是 venv\Scripts\python.exe，Linux 和 macOS 下是 venv/bin/python。使用这个解释器执行 pip install -r requirements.txt 才能把包装到正确环境。
# Windows，在 WebUI 根目录执行 cd extensions\插件文件夹名 ..\..\venv\Scripts\python.exe -m pip install -r requirements.txt # Linux / macOS cd extensions/插件文件夹名 ../../venv/bin/python -m pip install -r requirements.txt
依赖安装完成后，重新启动 WebUI，进入 Extensions 页面，在 Installed 标签下确认插件已加载。如果插件没有出现，检查 WebUI 启动日志中是否出现 ImportError 或 ModuleNotFoundError，这通常说明依赖没有装进当前使用的虚拟环境。
下载完插件还是报错怎么办
手动解压安装后，仍然可能遇到加载失败。比较常见的一种是文件夹名称带 -main 后缀影响插件识别。虽然 WebUI 一般会递归扫描 extensions 下一级目录，但部分插件内部使用相对路径，太深的目录层级会引发找不到模块。建议统一把文件夹改成插件名，去掉 GitHub 自动添加的分支后缀。
另一种问题是依赖版本冲突。例如某些插件要求 torch 或 numpy 的特定版本，而手动 pip install -r requirements.txt 时可能把 WebUI 核心依赖改坏。安装依赖前可以先查看 requirements.txt 内容，如果发现它会强制降级或升级核心组件，最好先备份环境，或只安装缺失的包而不是全部重装。控制台里出现 version conflict 时，针对具体包名单独安装版本通常比盲目重装更安全。
还有一类问题看起来像插件坏了，其实是权限或路径问题。Windows 用户如果把 WebUI 放在 C:\Program Files 或中文目录下，插件中的某些脚本可能因为空格、中文字符没有处理而运行失败。建议把整个 WebUI 目录移动到磁盘根目录或纯英文路径，例如 C:\ASR\stable-diffusion-webui。同时检查杀毒软件是否拦截了插件目录下的 .bat 或 .exe 文件。
# 在 WebUI 根目录查看启动日志中的插件错误 grep -i "error" webui.log | tail -n 30 # Windows PowerShell 可改用 Get-Content webui.log | Select-String -Pattern "error" | Select-Object -Last 30
改善 git 拉取成功率，减少重复手动操作
手动下载虽然稳定，但插件多了以后更新成本会变高。如果还想让 WebUI 自带的安装和更新功能正常工作，可以针对 git 的网络层做调整。一个低风险的做法是给 git 设置全局代理，前提是本地有可用的 HTTP 或 SOCKS 代理。命令如下：
# HTTP 代理 git config --global http.proxy http://127.0.0.1:7890 git config --global https.proxy http://127.0.0.1:7890 # 取消代理 git config --global --unset http.proxy git config --global --unset https.proxy
如果代理不稳定，可以尝试提升 Git 的传输缓冲区和超时阈值。对于较大的仓库，默认缓冲区可能导致 early EOF 或 RPC failed。执行 git config --global http.postBuffer 524288000 能显著提高传输忍耐度。还可以把 git 的版本协议限制为 HTTP/1.1，避免部分网络设备对 HTTP/2 支持不好：git config --global http.version HTTP/1.1。
另一个思路是使用国内代码托管平台的镜像仓库。以 Gitee 为例，可以在导入 GitHub 仓库后，手动把插件目录改成 git 仓库再指向镜像地址。这样后续 git pull 走境内网络，速度会稳定很多。操作流程是把已解压的插件目录初始化为 git 仓库，添加 Gitee 远程地址后拉取一次：
cd extensions/插件文件夹名 git init git remote add origin https://gitee.com/你的用户名/插件镜像.git git fetch origin git reset --hard origin/main
需要提醒的是，镜像仓库可能存在同步延迟，拉取前先确认 Gitee 上的提交时间和 GitHub 原仓库是否接近。如果插件紧急修复了某个兼容问题，但镜像还没同步，可以先回退到手动下载 zip 的方式，优先保证插件能用。
Stable Diffusion WebUI插件安装失败git pull报错修改时间：2026-10-04 03:01:58