解决 TimeoutError: [WinError 10060] 在 FramePack项目中连接 Hugging Face 超时的问题
#工作记录
以下是针对 TimeoutError: [WinError 10060] 的完整排查方案，适用于 FramePack项目中。
（一般该错误的发生原因请重点排查Hugging Face模型仓库受限需要登录的情形）
FramePack项目参考资料
FramePack部署（从PyCharm解释器创建和使用开始）保姆级教程-CSDN博客
接上篇，解决FramePack启动报错：“httpx.ReadError: [WinError 10054] 远程主机强迫关闭了一个现有的连接。“的问题_framepack 不能启动-CSDN博客
正常运行FramePack图生视频demo_gradio.py修改记录-CSDN博客
📌 错误描述
在使用 Python（尤其是 requests、urllib3 或 Hugging Face Hub）加载模型时，可能遇到如下错误：
TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。
最终通常表现为：
requests.exceptions.ConnectTimeout: HTTPSConnectionPool(host='huggingface.co', port=443): Max retries exceeded ...
🔍 发生原因
WinError 10060 是一个网络层面的连接超时错误，说明我们尝试访问的远程服务器（如 huggingface.co）在设定时间内未返回响应，可能是由于：
-
本地网络防火墙或杀毒软件拦截；
-
无法访问国外站点；
-
使用了错误或未开启的代理；
-
Hugging Face 是 受限（gated）模型仓库，需要登录验证；
-
DNS 配置错误或网络不可达。
✅ 解决方案汇总
✅ 1. 检查网络是否能访问 Hugging Face
先用浏览器访问模型页面，例如：
https://huggingface.co/lllyasviel/FramePackI2V_HY
或用命令行测试：
curl https://huggingface.co
如果能访问，则说明不是被阻挡；否则请继续下一步。
✅ 2. 配置代理
在 PowerShell 设置代理：
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
我们需要将
127.0.0.1:7890替换成自己科学上网软件（如XXXX）监听的 HTTP 代理端口。
✅ 3. 使用 Hugging Face Token 登录
部分模型是受限访问的，必须登录 Hugging Face 才能下载。
生成 Token：
前往 https://huggingface.co/settings/tokens 创建一个 read 权限的访问令牌。
登录 Hugging Face CLI：
huggingface-cli login
然后粘贴我们的 Token（输入不可见，按回车）。
然后输入Y（Yes）确认。
示例如下：
(.venv) PS F:\PythonProjects\FramePack> huggingface-cli login
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_|
_| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_|
_| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _|
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_|To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens .
Token can be pasted using 'Right-Click'.
Enter your token (input will not be visible):
Add token as git credential? (Y/n) Y
Token is valid (permission: fineGrained).
The token `stable_video_diffusion_img2vid.ipynb` has been saved to C:\Users\love\.cache\huggingface\stored_tokens
Your token has been saved in your configured git credential helpers (manager).
Your token has been saved to C:\Users\love\.cache\huggingface\token
Login successful.
The current active token is: `stable_video_diffusion_img2vid.ipynb`
(.venv) PS F:\PythonProjects\FramePack>
粘贴token：
输入Y确认：
成功之后我们会看到如下信息：
Your token has been saved to C:\Users\用户名\.cache\huggingface\token
完成后可以继续尝试访问模型：
可以看到已经没有以下报错信息了。
TimeoutError: [WinError 10060] 由于连接方在一段时间后没有正确答复或连接的主机没有反应，连接尝试失败。
✅ 4. 离线下载模型并本地加载（绕过联网）
在网络通畅机器上执行：
git lfs install
git clone https://huggingface.co/lllyasviel/FramePackI2V_HY
拷贝到我们的本地项目中后这样加载：
from diffusers_helper.models.hunyuan_video_packed import HunyuanVideoTransformer3DModelPackedtransformer = HunyuanVideoTransformer3DModelPacked.from_pretrained("./FramePackI2V_HY",torch_dtype=torch.bfloat16
).cpu()
✅ 5. 增加超时时间（备用方案）
如果是因为默认超时太短，可以手动设置较长超时时间，例如：
from huggingface_hub import hf_hub_downloadhf_hub_download(repo_id="lllyasviel/FramePackI2V_HY", timeout=60)
🧪 最佳实践：诊断代理是否生效
创建一个脚本测试我们的代理配置：
import requestsproxies = {"http": "http://127.0.0.1:7890","https": "http://127.0.0.1:7890",
}try:r = requests.get("https://huggingface.co", proxies=proxies, timeout=10)print("连接成功:", r.status_code)
except Exception as e:print("连接失败:", e)
✅ 总结
| 问题 | 解决方式 |
|---|---|
| 网络不可达 | 配置代理、检查 DNS |
| 模型访问受限 | 登录 Hugging Face、申请模型访问权限 |
| requests 超时 | 设置代理并延长 timeout |
| 本地项目部署 | 使用离线加载方式加载模型 |
如果我们正在使用如 Gradio、Diffusers、Transformers 等框架，并遭遇类似问题，这些方法基本都适用。