ComfyUI HuggingFace HttpRequestException: 修复 Hugging Face 模型下载失败

如果 ComfyUI 或某个启动器在下载模型时报告 HuggingFace HttpRequestException，先别急着重装 ComfyUI。

这类错误通常意味着下载器没能完成对 Hugging Face 的请求，或者 Hugging Face 因为仓库是 gated、private、被改名、或者根本不存在而拒绝了请求。你的 Python 环境本身很可能还是好的。

快速诊断

来自真实 ComfyUI 故障的数据证据

在本地 Wonderful Launcher issue 数据里，download_failed 配合 HttpRequestException 这个错误族，出现在多个稳定版本中，并被归类到 model_asset_loading。

ComfyUI issue 数据集里也能看到同一家族的不同表述：

• 下载 huggingface.co 时出现 MaxRetryError 和 SSL 失败
• Cannot connect to host huggingface.co:443
• Hub 访问不到且本地缓存里没有文件时出现 LocalEntryNotFoundError
• 节点访问 gated / private repo 时出现 HfHubHTTPError 或 unauthorized 响应
• 用户请求镜像支持或离线安装，因为大模型下载路径不稳定

所以这篇页面把它当成“下载路径诊断”问题来处理，而不是先把它归类成“ComfyUI 安装坏了”。

第 1 步：在 ComfyUI 外部测试精确 Hugging Face URL

先从日志里找出 URL 或 repo 名。它常见长这样：

https://huggingface.co/owner/repo/resolve/main/model.safetensors
owner/repo

先在同一台机器的浏览器里打开。然后再用终端测试：

Invoke-WebRequest -Uri "https://huggingface.co" -UseBasicParsing -TimeoutSec 20

如果是具体文件，优先用 HEAD 请求测试连通性，不要为了测试就下载一个几 GB 的模型：

curl.exe -L -I "https://huggingface.co/owner/repo/resolve/main/model.safetensors"

结果可以这样理解：

第 2 步：把网络问题和权限问题分开

Hugging Face 的 huggingface_hub 库会把 HTTP 失败细分成 RepositoryNotFoundError、GatedRepoError、RevisionNotFoundError、EntryNotFoundError 和 HfHubHTTPError 等错误。

对于 ComfyUI 用户来说，最实用的拆法是：

不要为了修 403 或 gated-model 错误去乱动 CUDA、Torch 或其他 Python 包。那是访问权限问题，不是运行时依赖问题。

第 3 步：在启动 ComfyUI 之前配置代理

如果你的浏览器只有走代理才能访问 Hugging Face，就要确保 ComfyUI 进程也拿到了同样的代理。

临时 PowerShell 会话：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
python main.py

Windows 便携包的 .bat 文件里，则要把代理写在 embedded Python 命令前面：

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
.\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build
pause

把 7890 换成你代理工具实际监听的端口。

如果 ComfyUI 是通过桌面应用、启动器、服务、计划任务，或者某个终端快捷方式拉起来的，就要在 真正拉起 ComfyUI 的那个位置 配代理。你在另一个终端里临时设置环境变量，对已经在跑的进程没有帮助。

第 4 步：检查 token 和 gated 模型权限

有些工作流和自定义节点会去 gated 或 private 的 Hugging Face 仓库拉模型。这时，光能打开公开 URL 还不够。

按这个顺序检查：

1. 登录状态下打开 Hugging Face 仓库页
2. 如果仓库是 gated，先接受模型许可或访问申请
3. 创建一个有读取权限的 token，或者用现成的有效 token
4. 把 token 传给真正启动 ComfyUI 的那个进程

临时 PowerShell 会话：

$env:HF_TOKEN = "hf_your_token_here"
python main.py

确认当前 Python 进程能看到 token：

python -c "import os; print('HF_TOKEN set:', bool(os.environ.get('HF_TOKEN')))"

确认当前 Python 进程能通过 huggingface_hub 完成认证：

python -c "import os; from huggingface_hub import HfApi; print(HfApi(token=os.environ['HF_TOKEN']).whoami()['name'])"

如果这个命令直接报 auth error，那就先修 token 或账号权限，不要继续折腾 ComfyUI。

第 5 步：检查离线模式和 Hugging Face 缓存

Hugging Face 通过 HF_HOME、HF_HUB_CACHE、HF_TOKEN、HF_HUB_OFFLINE 这些环境变量来控制缓存和离线行为。

先看当前进程能看到什么：

python -c "import os; print('HF_HOME=', os.environ.get('HF_HOME')); print('HF_HUB_CACHE=', os.environ.get('HF_HUB_CACHE')); print('HF_HUB_OFFLINE=', os.environ.get('HF_HUB_OFFLINE'))"

如果 HF_HUB_OFFLINE=1，那在文件没有提前进缓存的情况下，Hub 请求一定会失败。这种情况很像“下载坏了”，但根因其实是离线模式加空缓存。

关于缓存要小心：

• 不要手工改 Hugging Face 缓存目录里的文件。
• 不要因为一次失败就把整个缓存目录全删了，尤其是你已经下过很多大模型的时候。
• 如果只是某一次下载被中断，优先删那一个损坏的半截文件，或者换一个干净目录重下。

第 6 步：只有在节点支持时，才用手动下载兜底

手动下载比较适合普通模型文件，比如 .safetensors、.gguf、.pth、.bin、.onnx。

安全做法是：

1. 用浏览器或下载工具把文件下完整
2. 确认文件大小是完整的
3. 放到正确的 ComfyUI 目录
4. 重启 ComfyUI，或者刷新模型下拉框

常见目录：

完整目录映射请看 ComfyUI 里的 safetensors 应该放到哪里。

有些自定义节点并不会去标准 ComfyUI 模型目录找文件，而是直接调用 hf_hub_download()，期待文件出现在 Hugging Face 缓存或节点专用目录里。如果你手工摆文件还是不生效，就先看节点 README，再决定怎么放。

第 7 步：修下载时，别顺手把依赖环境搞漂了

除非日志明确说是 import 或版本要求失败，否则不要一上来就重装 torch、transformers 或 huggingface_hub。

这些问题是不同类目的：

最安全的顺序是：

1. 先保住当前可工作的环境
2. 测精确 URL
3. 修代理、token 和缓存
4. 只重下或移动缺失模型文件
5. 只有日志能证明是包问题时，才改包

Wonderful Launcher 在这里能帮什么

当模型下载问题和环境风险缠在一起时，Wonderful Launcher 会更有帮助：

• 它能把日志明确绑定到你启动的那个包
• 它方便你在修复前保住已有模型和工作流
• 它让你把稳定 ComfyUI 和实验 ComfyUI 分开
• 它能减少“在错误 Python 环境里乱跑 pip install”这种高风险动作

如果文件 URL 明明能通，但 ComfyUI 还是下载不到或识别不到模型，就先用启动器日志把精确 URL、目标路径、Python 环境和错误家族记下来，再决定要不要动依赖。

相关指南

• 下载模型
• ComfyUI 里的 safetensors 应该放到哪里
• ComfyUI Failed to Get Custom Node List
• ComfyUI 依赖冲突
• How to Fix ComfyUI Plugin Import Failed Errors
• 部署失败：下载资源包

资料来源

• Hugging Face Hub 文件下载指南
• Hugging Face Hub 文件下载 API
• Hugging Face Hub 环境变量
• Hugging Face Hub HTTP 错误工具函数
• ComfyUI issue: connection issue downloading models from Huggingface
• ComfyUI issue: cannot connect to host huggingface.co
• ComfyUI issue: MaxRetryError downloading from huggingface.co
• ComfyUI issue: LocalEntryNotFoundError cache miss