Stable Diffusion WebUI / ComfyUI 本地部署教程：2026 Civitai 模型下载、HuggingFace 权重加速与 GitHub 依赖报错终极排查

快速自查与核心排查决策树（30 秒定位故障）

作为当今全球开源生态最庞大、自由度最高、隐私可控性最强的生成式 AI 绘画框架，Stable Diffusion (SD WebUI / Forge) 以及基于节点流逻辑构建的 ComfyUI 是每一位严肃 AI 从业者、设计师与游戏美术师的必修利器。

然而，几乎 90% 的初学者在本地安装部署的第一天，都会被各种莫名其妙的命令行红字卡死在起跑线上。表面上看它是“离线运行在本地显卡上的软件”，但其初始环境安装、底层库克隆、节点安装更新以及动辄几十个 G 的模型权重拉取，无一不极度考验国际网络质量。

请参照下表迅速对照当前遭遇的具体报错形态，实施精准修复：

故障现象分类	命令行 / 界面典型报错提示	核心技术原因	快速解决措施
初始环境安装卡死	Installing torch and torchvision... 停留数十分钟无反应	官方 PyTorch 轮子包（>2.5GB）从境外拉取被限速超时	在脚本注入国内清华 pip 镜像源与官方 CUDA 独立源
Git 依赖克隆超时	fatal: unable to access 'https://github.com/...': Connection timed out	CMD / PowerShell 默认不读取系统代理，Git 子模块直连被墙	为 Git 注入全局 http.proxy，或开启客户端 TUN 模式
Hugging Face 权重死锁	Downloading clip-vit-large-patch14... 几 KB/s 甚至报错	Hugging Face 官方 CDN 在国内公网受到严重 QoS 限速与丢包	环境变量配置 HF_ENDPOINT="https://hf-mirror.com" 镜像端点
Civitai (C站) 打不开	浏览器访问 civitai.com 提示 1020 报错或一直转圈人机验证	C 站启用了 Cloudflare 高级防护，机房 IP 被拉入高欺诈分池	切换纯净低并发专线节点，清理浏览器 Cookie 或换无痕窗口
ComfyUI 节点拉取失败	ComfyUI Manager 安装自定义节点提示 Fetch Failed 或 Git 报错	节点仓库位于 GitHub，ComfyUI 后台未配置代理出口	编辑 custom_nodes 配置代理，或利用 Git 命令行手动克隆离线包

flowchart TD
    A["Stable Diffusion 部署与使用受阻"] --> B{"卡在哪个阶段？"}
    B -- 首次双击启动批处理脚本 --> C{"报错提示是什么？"}
    C -- Installing torch 卡住 / 报错 --> D["PyTorch 境外轮子下载受阻"]
    D --> E["配置 pip 镜像源与本地代理环境变量"]
    C -- Git clone 子模块报错超时 --> F["GitHub 网络受阻"]
    F --> G["设置 git config 全局代理 (127.0.0.1:7890) 或开启 TUN 虚拟网卡"]
    B -- 模型权重与资源下载 --> H{"下载来源是何处？"}
    H -- Hugging Face 权重下载极慢 --> I["配置 HF_ENDPOINT 镜像源加速下载"]
    H -- Civitai (C站) 打不开或断连 --> J["Cloudflare 拦截或公网丢包，使用多线程下载器挂载专线代理"]
    B -- ComfyUI 运行期 --> K["ComfyUI Manager 节点安装失败，进入 custom_nodes 手动 Git 克隆"]

---

本地跑 SD 架构机理深度解密：为什么本地离线工具极度依赖外网？

许多人误以为：“我花上万元配了 RTX 4090 显卡，只要本地算力够大，断网也能玩转 SD。”这种观点只对了一半。一旦脱离了完善的全球开源依赖生态，本地的 WebUI 和 ComfyUI 本质上只是一个毫无生气的空壳。

1. 庞大的多源分布式依赖拓扑

以最经典的 AUTOMATIC1111 SD WebUI 为例，其初始启动脚本 webui-user.bat（Linux/Mac 上为 webui.sh）在第一次运行时，后台会自动触发一个极其复杂的级联下载链条：

启动脚本级联下载拓扑图：
[webui-user.bat 启动]
       │
       ├─► 步骤 1: 检查 Python 基础运行环境 (Python 3.10.x 虚拟环境 venv)
       │
       ├─► 步骤 2: 从 PyPI / PyTorch 官方拉取巨型 Wheel 轮子 (2.5GB+)
       │    └── download.pytorch.org/whl/cu121 ──► 极易因连接重置 (TCP RST) 导致下载回滚
       │
       ├─► 步骤 3: 从 GitHub 递归克隆 10 余个开源子模块依赖仓库
       │    ├── Stability-AI/generative-models (核心生成管线)
       │    ├── CompVis/taming-transformers (离散表征分词)
       │    ├── crowsonkb/k-diffusion (Karras 采样器算法库)
       │    ├── sczhou/CodeFormer (人脸高清修复算法模型)
       │    └── salesforce/BLIP (图片反推提示词多模态模型)
       │    └── 【致命痛点】：只要其中任何一个 Git 仓库连接超时，整段脚本立即崩溃退出!
       │
       └─► 步骤 4: 从 Hugging Face 拉取文本分词与安全审查模型 (CLIP-ViT 权重)
            └── huggingface.co/openai/clip-vit-large-patch14 (3GB+)

2. 为什么开了普通系统代理，命令行依然死活连不上？

这是新手最常踩中的经典巨坑：在桌面右下角开了代理客户端，浏览器看 YouTube 飞快，但双击 webui-user.bat 却依然狂报 Connection timed out。

• 操作系统机制：Windows 客户端默认开启的“系统代理”，仅仅是将代理端口写入了系统注册表（WinINet API）。只有遵循此规范的现代图形浏览器（Chrome/Edge）才会主动读取。
• 命令行与 Python 的脱节：Windows 命令提示符（CMD）、PowerShell、Git 命令行工具以及 Python 底层的 urllib / requests 网络库，默认根本不读取 Windows 系统代理注册表！
• 它们在执行网络请求时，遵循的是纯粹的 Linux 风格环境变量约定 —— HTTP_PROXY 与 HTTPS_PROXY。如果开发者没有在当前终端会话或系统环境中显式声明这两个变量，所有的 git clone 和 pip install 都会无视你开的梯子，以完全未代理的状态硬闯国内公网防火墙，结果必然是连接超时与抛出红字异常。

---

彻底解决本地部署卡住的黄金配置全景手册

想要一劳永逸地驯服 SD WebUI 与 ComfyUI 的启动环境，必须在命令行层级、Python 依赖层级与 Git 层级完成全链路打通。

1. 修改启动批处理脚本（彻底注入代理环境变量）

最省心、最稳妥的方法是直接将代理注入启动脚本内部，这样每次双击运行时全自动挂载加速，绝不影响日常其他软件。

Windows 平台（修改 webui-user.bat）：

右键用记事本或 VS Code 打开 SD WebUI 根目录下的 webui-user.bat，在 @echo off 下方添加代理与显存优化参数：

@echo off

:: 声明 Python 解释器路径（若已配置系统 Path 可留空）
set PYTHON=

:: 声明虚拟环境目录
set VENV_DIR=

:: 【关键配置】：显式注入本地网络客户端的 HTTP/HTTPS 代理端口
set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

:: 【关键配置】：声明 Hugging Face 官方国内高速镜像端点
set HF_ENDPOINT=https://hf-mirror.com

:: 【进阶调优参数】：包含 xformers 显存加速、跨步注意力优化与自动打开浏览器
set COMMANDLINE_ARGS=--xformers --opt-sdp-attention --autolaunch --enable-insecure-extension-access

call webui.bat

注意端口核对：请务必确认你本地客户端的本地端口是 7890（Clash 默认）、10809（v2rayN 默认）还是 2080（Sing-box 默认）。

---

2. 为 Git CLI 显式配置全局代理

在安装 WebUI 的各种功能扩展（如 ControlNet、OpenPose、Reactor 换脸插件）以及 ComfyUI 自定义节点时，系统频繁调用本地 Git 命令拉取代码。

打开 PowerShell 或 CMD，执行以下命令为 Git 写入代理：

# 为 Git 配置 HTTP 与 HTTPS 全局代理转发
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 验证 Git 代理配置是否生效
git config --global --get http.proxy

# （备用）若日后需要取消 Git 代理，执行以下两条命令：
# git config --global --unset http.proxy
# git config --global --unset https.proxy

---

3. 配置国内权威 pip 镜像源（解决 Installing 依赖超时）

为了避免在安装 PyTorch、torchvision、numpy、scipy 等庞大依赖库时遭遇长达数小时的龟速拉取，建议永久将本地 Python 的 pip 源切换至清华大学或阿里云镜像源：

# 打开 PowerShell 执行，全局配置清华大学开源镜像站作为默认 pip 源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 配置信任主机，防止因 SSL 校验引起报错
pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

---

Hugging Face 权重模型高速拉取实战（终结卡在 CLIP 阶段）

WebUI 在首次生成图片或加载模型时，往往会自动从 Hugging Face 下载基础视觉分词模型（如 openai/clip-vit-large-patch14）。如果直连官方 huggingface.co，由于其后端托管在 AWS S3 上，国内经常出现几十 KB/s 的龟速下载甚至直接中断报错 OSError: We couldn't connect to 'https://huggingface.co'。

1. 启用开源公益镜像站（HF-Mirror）

国内顶尖技术社区搭建了 100% 完整镜像同步的官方中继站 —— hf-mirror.com。

Linux / macOS 终端配置：

export HF_ENDPOINT="https://hf-mirror.com"

Windows PowerShell 终端配置：

$env:HF_ENDPOINT = "https://hf-mirror.com"

2. 使用官方 huggingface-cli 开启多线程极速离线下载

如果你需要手动拉取数十个 G 的官方基础大模型（如 SDXL Base 1.0、Flux.1-dev、Stable Video Diffusion），推荐使用多线程命令行工具一键满带宽下载：

# 1. 在 Python 环境中安装官方命令行工具与加速传输库
pip install -U "huggingface_hub[hf_transfer]"

# 2. 开启高速传输模式
$env:HF_HUB_ENABLE_HF_TRANSFER = "1"
$env:HF_ENDPOINT = "https://hf-mirror.com"

# 3. 多线程下载指定大模型 Checkpoint 到本地指定文件夹
huggingface-cli download --resume-download black-forest-labs/FLUX.1-dev --local-dir D:/AI-Models/FLUX.1-dev

---

Civitai (C站) 无法访问与大型权重模型多线程高速下载

Civitai（俗称 C 站） 是全球最大的开源模型分享社区。成千上万创作者将自己训练的精美 LoRA、Embedding、VAE 以及微调底模发布在上面。

1. C 站访问受阻与 Cloudflare 拦截破解

很多用户访问 civitai.com 时，浏览器持续卡在“正在验证您是否是真人”的人机验证死循环，或者直接弹出 Error 1020: Access Denied。

• 根本原因：C 站遭受频繁的恶意爬虫攻击，部署了极高等级的 Cloudflare 防火墙。大量廉价机场的公共出口 IP 欺诈分过高，被直接列入阻止访问清单。
• 破解法门：将网络节点切换至纯净的低并发专线出口，清空浏览器包含 civitai 的缓存数据；使用 Chrome 隐身模式即可顺利通过验证码进入。

2. C 站几十 G 模型高速断点续传（IDM / Motrix 实战）

C 站上的大型底模（如 SDXL Checkpoint）单个文件通常在 6GB ~ 12GB 左右。直接使用浏览器自带的单线程下载器极易在下到 90% 时突然网络抖动宣告失败，且无法断点续传。

推荐方案：开源下载神器 Motrix + 本地代理挂载

1. 下载并安装开源多线程下载管理器 Motrix。
2. 打开 Motrix 设置 -> 进阶设置（Advanced）：
   • 找到 代理（Proxy） 选项，选择并填入：http://127.0.0.1:7890（填入你的本地代理监听端口）。
   • 将最大并发任务数调整为 16 或 32 线程。
3. 在 Civitai 模型页面，右键点击下载按钮，选择 “复制链接地址”。
4. 粘贴至 Motrix 中新建下载，利用多线程并发技术可轻松跑满百兆专线带宽，且中途网络抖动全自动支持断点续传。

模型文件存放标准目录指南：
├── 大模型底模 (Checkpoint) ──► models/Stable-diffusion/ (如 v1-5-pruned.safetensors, SDXL.safetensors)
├── 微调风格特征模型 (LoRA) ──► models/Lora/ (如 KoreanDollLikeness.safetensors)
├── 画面色彩校正文件 (VAE)  ──► models/VAE/ (如 vae-ft-mse-840000-ema-pruned.safetensors)
└── 控制网结构模型 (ControlNet) ─► extensions/sd-webui-controlnet/models/

---

ComfyUI 节点生态与 Manager 极速修复实战

与将所有功能堆砌在单页面的 WebUI 相比，ComfyUI 采用了更加现代、模块化的图形节点流（Node Graph）架构。其最大优势在于：显存利用率极其出色（比 WebUI 节省 20%~30% 显存），且图片生成速度更快，更适合搭建自动化生产管线。

1. 核心扩展：ComfyUI Manager 安装与连通调优

ComfyUI 的灵魂在于由社区开发者维护的成百上千个第三方自定义节点（Custom Nodes）。而管理这些节点的最佳工具就是 ComfyUI-Manager。

手动部署 ComfyUI Manager：

打开命令行，切换至你的 ComfyUI 根目录下的 custom_nodes 文件夹：

# 进入自定义节点插件目录
cd ComfyUI/custom_nodes

# 通过 Git 挂载代理直接克隆官方管理器仓库
git clone https://github.com/ltdrdata/ComfyUI-Manager.git

解决 Manager 界面中点击“Install”提示 Fetch Failed：

很多用户在启动 ComfyUI 后，点击界面的 Manager -> Install Custom Nodes，列表一片空白或报错 Fetch Failed。

• 原因：Manager 默认需要向 GitHub 实时拉取一份庞大的 custom-node-list.json 元数据索引文件。
• 实战修复：
  1. 打开 ComfyUI/custom_nodes/ComfyUI-Manager/config.ini。
  2. 找到 channel_url 配置项，将其官方默认的 GitHub Raw 链接修改为支持国内加速的反代通道，或者直接在启动 ComfyUI 的批处理脚本中像 WebUI 一样写入 set HTTP_PROXY=http://127.0.0.1:7890，彻底打通节点的下载网络。

---

为什么廉价公共机场无法维系高强度 SD/ComfyUI 生产？

很多从事 AI 绘画与商业设计的从业者常常疑惑：“我只是下载几个开源模型，为什么非要选用企业级专线不可？”

1. 大文件下载时的 TCP 截断与校验灾难： 廉价机场往往通过公网服务器进行多次中转。在传输 10GB 以上的巨型二进制权重文件时，极易因跨境骨干网丢包发生 TCP 窗口暴跌甚至连接中断。更致命的是，部分廉价中转服务器存在数据包丢失导致的模型文件静默损坏（Silent Data Corruption）。下完后在 WebUI 中加载时，直接弹出 safetensors_rust.SafetensorError: Error while deserializing header: MetadataIncompleteBuffer，排查半天最终只能无奈删掉重新下载。
2. 多线程并发流量被中转服务器暴力限速： 从 Civitai 或 HuggingFace 开启 16 线程满速拉取模型时，廉价小作坊服务商为了防止单个用户耗尽中转机带宽，通常会设置极其严厉的 QoS 流量整形（Traffic Shaping），下载两分钟后速度立即被腰斩至 500KB/s。

---

常见疑难杂症与深度故障解答（FAQ）

Q1：为什么生成的图片有时候全黑（纯黑图）或者纯绿图？

答：这通常是由于精度计算与显卡硬件特性不兼容引起的常见错误：

1. 半精度溢出（FP16 Overflow）：部分 GTX 16 系列显卡（如 1660、1650）或特定旧架构显卡在执行 FP16 浮点运算时会出现 NaN 溢出。在启动参数中追加 --no-half 强制使用单精度运算（FP32）即可彻底根除黑图。
2. VAE 缺失或损坏：如果所使用的 Checkpoint 底模没有内置 VAE（变分自编码器），生成出来的画面就无法被正确反算为可见像素。在 WebUI 设置中手动指定一个通用的外挂 VAE（如 vae-ft-mse-840000-ema-pruned）即可恢复正常。

Q2：提示 CUDA out of memory 显存爆满崩溃如何拯救？

答：

• 追加内存优化参数：在 COMMANDLINE_ARGS 中加入 --medvram（针对 6GB~8GB 显卡）或 --lowvram（针对 4GB 显卡），这会将部分计算图动态分块卸载至内存，大幅降低显存峰值占用。
• 安装 xFormers 库：开启 --xformers，这能极大地重组注意力计算矩阵，通常能瞬间释放 1.5GB 以上的显存空间并提升 20% 出图速度。
• 降低初始出图分辨率：SD 1.5 模型严禁直接用 1024x1024 出图（必然爆显存）。正确的做法是以 512x512 初始渲染，随后开启 Hires. fix（高分辨率修复） 放大画面。

Q3：模型格式 .safetensors 与 .ckpt 到底有什么本质区别？

答：

• .ckpt（Checkpoint）：采用 Python 原生 pickle 模块序列化存储。存在极高安全风险！黑客可以在 ckpt 权重中嵌入恶意 Python 代码，一旦加载该模型，恶意代码就会在本地被静默执行，导致电脑被植入木马。
• .safetensors（安全张量格式）：由 Hugging Face 主导推行的新一代纯只读二进制格式。仅存储纯净的神经网络权重张量数值，完全杜绝了代码执行能力，且加载读取速度比旧版 ckpt 快 2 倍以上。在 Civitai 下载时请务必 100% 优先选择 .safetensors 格式。

---

总结与 SD / ComfyUI 本地生产环境终极清单

要想在本地无拘无束地释放开源生成式 AI 的无限想象力，请牢记以下四大底层系统维护法则：

1. 启动脚本常备代理：在 webui-user.bat 中硬编码 HTTP_PROXY 与 HF_ENDPOINT，彻底终结子模块与分词器安装卡死。
2. 善用国内镜像分流：pip 换源清华大学，HuggingFace 认准 hf-mirror，充分利用开源社区的高速镜像基础设施。
3. 多线程工具拉取大模型：利用 Motrix / IDM 挂载本地代理端口并发拉取 Civitai 大模型，拒绝单线程断连悲剧。
4. 专线网络构筑长城：选择具备高带宽、零丢包的 IEPL 内网专线，保障几十 G 大模型下得快、下得稳、绝不损坏。

如需进一步了解操作系统底层网络调谐、AI 开发者专线方案与代理工具深度横评，请继续参阅下方核心指南：

• 操作系统底层网络代理设置与环境变量注入
• AI 开发者与 API 高速专线网络方案
• 主流代理工具协议深度对比与分流规则指南
• 光速云 5 年老牌服务深度评测与使用指南