Hugging Face 模型下载卡住/超时（国内）——HF_ENDPOINT 切 hf-mirror，代码零改动

你会遇到什么

国内跑 AI 项目，transformers / huggingface-cli 下载模型时卡在 Fetching xx files 或一直转圈，最后超时报错（Could not connect to huggingface.co 类）。你以为是网速问题，重试 N 次还是一样——因为问题不在网速，在 huggingface.co 这个域名本身国内不可达。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

huggingface_hub 的所有下载入口（hf_hub_download / snapshot_download / huggingface-cli / transformers.from_pretrained）统一读环境变量 HF_ENDPOINT 拼接下载基址。

这是「改一个变量、全家生效」的机制根因：上层库（transformers/vllm/langchain）内部都调 huggingface_hub，不存在各自独立的下载路径。

注意新版默认走 Xet 传输协议（HF_HUB_DISABLE_XET=1 可关掉退回普通 HTTP），个别网络在 Xet 通道上失败但镜像可通，是第二类误判源。确定性判断路径是「双打点」：curl -w "%{http_code} %{time_total}" 分别打官方域名与 hf-mirror，000+超时 vs 200 = 直连问题实锤，不用猜。

Hugging Face 官方域名（huggingface.co）未对国内网络做加速，直连在传输层就被丢弃（2026-09-01 实测：curl https://huggingface.co/ 8 秒超时，code=000）。而国内镜像 hf-mirror.com 稳定可达（同实测：200，0.6 秒）。

关键机制：huggingface_hub 库的所有下载入口（hf_hub_download / snapshot_download / huggingface-cli / transformers.from_pretrained）都认环境变量 HF_ENDPOINT——改一个环境变量，全部代码零改动走镜像。这是镜像方案的核心价值：不用改代码、不用改依赖。

一步步来

1. 先确认是不是直连问题 — 必做（一锤定音）

curl -s -o /dev/null -w '%{http_code} %{time_total}s
' --max-time 8 https://huggingface.co/
# 000 / 超时 = 直连不可达，走第 2 步
curl -s -o /dev/null -w '%{http_code} %{time_total}s
' --max-time 8 https://hf-mirror.com/
# 200 = 镜像可用

2. 设 HF_ENDPOINT 后重试下载 — 必做（代码不用改）

还失败，看具体报错：

• 报证书/代理类错误 → 检查代理环境变量（见 proxy-env-var 条目，大小写坑）与 HF_HUB_DISABLE_XET=1（新版本默认走 Xet 协议，个别网络要关掉改普通 HTTP 下载）；
• 报 not found / 404 → 仓库名或文件名写错，镜像与官方仓库结构一致，直接对官方 URL 核对路径。

3. 缓存位置 — 可跳

HF_HOME（默认 ~/.cache/huggingface）控制下载缓存；换机器/清理时删它重下即可，与镜像无关。

4. 离线场景 — 可选

下载好的 HF_HOME 整个目录拷到内网机器，设同样的 HF_HOME 即可离线加载（transformers 优先读本地缓存）。

怎么确认修好了

# 1. 环境变量生效
echo $HF_ENDPOINT        # 应输出 https://hf-mirror.com
# 2. 实际下载成功（耗时可见）
huggingface-cli download sshleifer/tiny-gpt2 config.json
# 输出本地路径即成功；同一文件二次下载走缓存，秒回

其它环境的表现

症状

国内跑 AI 项目的典型形态：

• transformers / huggingface-cli / hf_hub_download 卡在 Fetching xx files 或一直转圈，最终超时（Could not connect to huggingface.co 类）；
• 重试 N 次结果一样——不是网速波动，是 huggingface.co 这个域名在国内传输层就被丢弃；
• 换机器、换网络（如手机热点）仍然失败；而访问 hf-mirror.com 秒开。

同族但别在本页死磕：报证书/代理类错误 → 检查代理环境变量（大小写坑见 proxy-env-var）与 HF_HUB_DISABLE_XET=1；报 404/not found → 仓库名/文件名写错，不是网络问题。

原因

huggingface_hub 的所有下载入口（hf_hub_download / snapshot_download / huggingface-cli / transformers.from_pretrained）统一读环境变量 HF_ENDPOINT 拼接下载基址——这是「改一个变量、全家生效」的机制根因：上层库（transformers/vllm/langchain）内部都调 huggingface_hub，不存在各自独立的下载路径。注意新版默认走 Xet 传输协议（HF_HUB_DISABLE_XET=1 可关掉退回普通 HTTP），个别网络在 Xet 通道上失败但镜像可通，是第二类误判源。确定性判断路径是「双打点」：curl -w "%{http_code} %{time_total}" 分别打官方域名与 hf-mirror，000+超时 vs 200 = 直连问题实锤，不用猜。

Hugging Face 官方域名（huggingface.co）未对国内网络做加速，直连在传输层被丢弃（2026-09-01 实测 8 秒超时 code=000）；国内镜像 hf-mirror.com 稳定可达（同实测 200/0.6s）。关键机制：huggingface_hub 的所有下载入口（hf_hub_download / snapshot_download / huggingface-cli / transformers.from_pretrained）都认环境变量 HF_ENDPOINT——改一个环境变量，代码零改动走镜像。

解法

1. 设 HF_ENDPOINT=https://hf-mirror.com（加到 ~/.bashrc 永久生效，一键命令见「快速修复」），代码不用改。
2. 先一锤定音确认是不是直连问题（见「快速修复」/「一步步来」第 1 步）：curl -w "%{http_code} %{time_total}" 分别打官方域名和镜像，000+超时 vs 200 = 直连问题实锤。
3. 还失败按报错分流：证书/代理类错误 → 查代理变量与 HF_HUB_DISABLE_XET=1；404 → 核对仓库路径。
4. 容器显式传：Docker 不继承宿主变量，docker run -e HF_ENDPOINT=... 或 compose environment: 补上。
5. 离线场景：把 HF_HOME 整个目录拷到内网机器，设同样的 HF_HOME 即可离线加载。