Mac M4 安装 sd-webui 踩坑全记录

想在 Apple Silicon Mac 上本地跑 Stable Diffusion，安装过程远比想象中麻烦：CLIP wheel 构建失败、Stability AI 仓库已删、HuggingFace 连不上，每一关都能劝退新手。本文把每个坑的原因和解法整理清楚，照着做可以少走几个小时弯路。

本地跑 Stable Diffusion 的想法很简单，执行起来就不是那么回事了。从 AUTOMATIC1111 的 sd-webui 克隆下来，bash webui.sh 一敲，错误接连出现。以下是完整的踩坑过程和对应解法。

坑一：CLIP wheel 构建失败

安装过程中出现的第一个拦路虎：

vbnet 复制代码

ERROR: Failed to build 'https://github.com/openai/CLIP/archive/d50d76d...zip'
when getting requirements to build wheel

根本原因是 setuptools 版本过高（70+），改变了 wheel 构建行为，与 CLIP 的旧版 setup.py 不兼容。解决方法是降级 setuptools，再加 --no-build-isolation 让 pip 跳过隔离，直接用当前环境里已装好的版本来构建：

bash 复制代码

# 激活 venv
source venv/bin/activate

# 降级 setuptools
pip install setuptools==69.5.1

# 重装 CLIP，跳过构建隔离
pip install git+https://github.com/openai/CLIP.git@d50d76daa670286dd6cacf3bcd80b5e4823fc8e1 \
    --no-build-isolation

--no-build-isolation 是什么：pip 默认在临时隔离环境里构建 wheel，与你当前环境完全隔开。加上这个参数后，pip 跳过隔离，直接用你手动装好的 setuptools 来构建，绕过了版本冲突。这是应急手段，不建议日常使用。

如果报 ModuleNotFoundError: No module named 'pkg_resources'，同样是 setuptools 问题，强制重装即可：

bash 复制代码

pip install --force-reinstall setuptools==69.5.1

坑二：git 要求输入 GitHub 账号密码

克隆依赖仓库时卡住，终端提示 Username for 'https://github.com':。GitHub 早已废除密码登录，这里需要用 SSH 或 Token。最一劳永逸的方法是告诉 git 把所有 HTTPS 请求自动转成 SSH：

bash 复制代码

git config --global url."git@github.com:".insteadOf "https://github.com/"

前提是本机已有 SSH key 并添加到 GitHub。没有的话先生成：

bash 复制代码

ssh-keygen -t ed25519 -C "your_email@example.com"
cat ~/.ssh/id_ed25519.pub   # 复制公钥，粘贴到 GitHub Settings - SSH keys

坑三：Stability AI 仓库已删，克隆报 404

这是 2025 年底开始出现的一个新问题。sd-webui 安装时需要克隆 Stability-AI/stablediffusion，但这个仓库已经被删除或设为私有，所有新装用户都会遇到：

vbnet 复制代码

RuntimeError: Couldn't clone Stable Diffusion.
remote: Repository not found.

官方在 dev 分支已将克隆源改为可用的 fork，切换过去即可：

bash 复制代码

cd /path/to/stable-diffusion-webui
git checkout dev
bash webui.sh

不想换分支的话，手动克隆 fork 仓库也行，克隆完 webui 会自动跳过这步：

bash 复制代码

cd repositories
git clone https://github.com/w-e-w/stablediffusion.git \
    stable-diffusion-stability-ai

坑四：HuggingFace 下载超时，模型和 tokenizer 全卡死

国内访问 HuggingFace 不稳定，默认模型（4GB 的 SD 1.5）和 CLIP tokenizer 都要从那里拉，一旦网络不通就卡住不动。最简单的修法是写入 webui-user.sh，让所有请求走镜像：

bash 复制代码

# webui-user.sh
export HF_ENDPOINT=https://hf-mirror.com

如果 tokenizer 已经报错退出，需要手动把文件预下载到 HuggingFace 缓存目录：

bash 复制代码

mkdir -p ~/.cache/huggingface/hub/models--openai--clip-vit-large-patch14/snapshots/main
cd ~/.cache/huggingface/hub/models--openai--clip-vit-large-patch14/snapshots/main

BASE=https://hf-mirror.com/openai/clip-vit-large-patch14/resolve/main
for f in tokenizer.json tokenizer_config.json vocab.json merges.txt \
          special_tokens_map.json config.json preprocessor_config.json; do
    curl -L -o $f $BASE/$f
done

7 个文件全部下完，再重新运行 webui.sh 即可跳过这步。

M4 专属优化配置

踩完以上四个坑，webui 终于能启动了。但 Apple Silicon 上还有性能调优的空间，把以下配置写入 webui-user.sh，一次到位：

bash 复制代码

#!/bin/bash
export HF_ENDPOINT=https://hf-mirror.com
export PYTORCH_ENABLE_MPS_FALLBACK=1
export PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.75   # 16GB 内存推荐值

export COMMANDLINE_ARGS="
  --skip-torch-cuda-test
  --no-half
  --upcast-sampling
  --opt-sub-quad-attention
  --use-cpu interrogate
"

几个参数的说明：--no-half 是因为 M4 的 MPS 对 float16 支持不稳定，用 float32 更安全；--upcast-sampling 防止生成图出现黑块；--opt-sub-quad-attention 是 Apple Silicon 上效果最好的 attention 实现；--use-cpu interrogate 把图像反推功能切回 CPU，MPS 上有已知 bug。

确认 MPS 可用：

bash 复制代码

python -c "import torch; print(torch.backends.mps.is_available())"
# 应该输出 True

M4 跑 SD 1.5 模型，512x512 分辨率 20 步大约 15-25 秒，日常使用体验流畅。推荐采样器用 DPM++ 2M，同等质量下步数可以压到 15 步，速度再快一截。

整个安装过程踩了四个坑，每个坑背后都有具体原因：setuptools 版本兼容性、GitHub 认证方式变化、上游仓库被删、国内网络访问限制。理解原因比记住命令更重要，下次遇到类似报错才能快速定位。

报错不是障碍，是理解工具运作方式的入口。

我是 Yuguo，软件设计师，正在用 AI 重构自己的开发工作流。

踩过的坑、跑通的方案、省下来的时间，都记在公众号 Feed 。

扫码关注，一起把 AI 真正用起来。