中国大陆配置 Hugging Face 镜像指南：用 hf-mirror.com 提高下载稳定性
一篇面向中国大陆开发者的 Hugging Face 镜像配置实用指南，涵盖临时环境变量、永久配置、huggingface-cli 下载和常见问题。
在北京、上海等中国大陆地区使用 Hugging Face，最常见的问题不是不会用，而是连不上，或者能连上但速度慢得让人怀疑人生。
这时候，与其反复重试官方源，不如直接把下载入口切到国内镜像。对大多数开发者来说，当前更省事、也更容易落地的方案，就是把 HF_ENDPOINT 配置到 hf-mirror.com。
这篇文章不绕弯子，直接给出能用的方法。你可以根据自己的使用场景，选择临时配置、永久配置，或者配合 huggingface-cli 下载模型。
为什么要配镜像
镜像主要解决的是访问连通性和下载速度问题。
如果你在中国大陆直接访问 Hugging Face 官方服务，常见情况包括：
- 请求超时
- 下载速度非常慢
- 大模型拉取过程频繁中断
把请求入口切到镜像后，通常能显著改善这些问题。但要明确一点：镜像并不等于绕过官方权限控制。如果某个模型本身需要授权，还是要先在 Hugging Face 官方完成申请和登录。
一、临时设置环境变量
如果你只是想先跑通一次下载，或者只在当前终端里使用 Hugging Face，那么最简单的办法就是设置临时环境变量。
Linux / macOS
export HF_ENDPOINT=https://hf-mirror.com
Windows CMD
set HF_ENDPOINT=https://hf-mirror.com
Windows PowerShell
$env:HF_ENDPOINT = "https://hf-mirror.com"
这种方式的优点很直接：上手快、改动小、马上生效。
它的限制也很明显：只对当前终端会话有效。你关掉窗口之后，就需要重新设置一次。
二、永久写入环境变量
如果你经常要下载模型、数据集，或者长期使用 transformers、diffusers、huggingface_hub，那就别每次手动执行命令了，直接做成永久配置。
Linux
把下面这行加入 ~/.bashrc 或 ~/.zshrc：
export HF_ENDPOINT=https://hf-mirror.com
保存后执行：
source ~/.bashrc
如果你用的是 zsh，也可以执行：
source ~/.zshrc
Windows
打开“系统属性” -> “环境变量”，新建一个用户变量：
- 变量名：
HF_ENDPOINT - 变量值：
https://hf-mirror.com
这样做的好处是，一次配置，后面基本不用再管。
三、配合 huggingface-cli 下载模型
如果你需要下载比较大的模型，或者希望支持断点续传，那么命令行工具通常比你在代码里临时拉取更稳一些。
先安装官方工具：
pip install -U huggingface_hub
确认已经设置好镜像地址后，再执行下载：
huggingface-cli download --resume-download gpt2 --local-dir gpt2
这个命令的好处在于：
- 对大模型下载更友好
- 支持断点续传
- 更适合在服务器或远程开发环境里使用
如果你只是想快速验证镜像是否生效，用 gpt2 这样的公开模型做测试通常就够了。
四、也可以直接在 Python 代码里指定
有些人不想改系统环境变量，担心影响别的项目。那也可以把镜像配置写在 Python 代码最前面：
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
这种方式适合项目内自包含的配置，尤其适合临时脚本、实验代码，或者你只想让某一个项目走镜像。
五、几个常见问题
1. 设了镜像，为什么有些模型还是下不下来？
镜像解决的是访问和下载速度问题，不等于绕过权限控制。
像 Llama 一类受限模型，仍然需要你先去 Hugging Face 官方页面申请访问权限，然后用官方账号的 Access Token 登录。
2. Token 应该怎么处理？
如果模型需要鉴权，可以先登录：
huggingface-cli login
然后按提示输入你在 Hugging Face 官网生成的 Token。
3. 环境变量和代码设置，应该选哪个？
如果你是个人开发者，平时经常下载模型，我更建议直接配环境变量。
如果你在维护项目，尤其是需要让项目在特定环境下稳定运行，那么写进代码或启动脚本会更可控。
六、一个更务实的建议
很多人在中国大陆折腾 Hugging Face，不是因为不会配，而是因为总想一次性把所有网络问题都解决掉。
其实没必要。大多数情况下，只要先把 HF_ENDPOINT 指到 https://hf-mirror.com，下载体验通常就会立刻改善一大截。剩下的问题，再根据模型权限、CLI 使用方式、服务器环境逐个处理就行。
先跑通，再优化，这通常才是成本最低的路径。
参考链接
- https://cloud.tencent.com/developer/article/2454491
- https://www.cnblogs.com/xyz/p/17938947
- https://blog.csdn.net/weixin_66004222/article/details/152168871
- https://blog.csdn.net/lanlinjnc/article/details/136709225
- https://www.wsisp.com/helps/48027.html
- https://blog.csdn.net/weixin_28840811/article/details/155976502
