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

症状

国内跑 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](proxy-env-var.html)）与 `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` 即可离线加载。

验证证据

- 2026-09-01 本机实测（WSL Ubuntu 26.04 无代理，huggingface_hub 1.29.0）：`实测复现日志（2026-09-01）`

- `curl https://huggingface.co/`：8 秒超时 code=000（直连不可达，实锤）；

- `curl https://hf-mirror.com/`：200 / 0.6s（镜像可用，实锤）；

- 直连 `hf_hub_download(sshleifer/tiny-gpt2, config.json)`：12 秒挂起被 timeout 杀掉（exit=124，实锤）；

- `HF_ENDPOINT=https://hf-mirror.com` 后同一调用：1.2 秒成功，662 字节（实锤）；代码零改动。