永久设置环境变量存放本地模型路径：用户级与系统级全攻略

知识分享

2026-07-29 10:40

19 阅读

永久设置环境变量存放本地模型路径的核心是编辑用户级或系统级 Shell 配置文件，添加 export 语句并执行重新加载，之后新启动的终端或服务都会自动使用你指定的目录。
常用变量包括 HF_HOME（Hugging Face）、TRANSFORMERS_CACHE、TORCH_HOME 等。

适用场景与准备工作

如果你经常使用 Python 深度学习框架（如 PyTorch、TensorFlow）或 Hugging Face Transformers，模型文件默认会下载到用户目录下的 .cache（如 ~/.cache/huggingface/）。
当系统盘空间有限时，你需要将模型存放到数据盘或大容量挂载点。

准备条件：

一台 Linux 服务器或本地 Linux 环境（本文以 Ubuntu 22.04 为例，CentOS 同理）。
拥有目标路径的写入权限（建议提前创建好目录，例如 /data/models）。
确认当前 Shell 类型（echo $SHELL，常见为 bash 或 zsh）。

用户级永久设置：修改 ~/.bashrc

用户级设置只会影响当前用户，适合单用户开发环境。

打开 ~/.bashrc 文件：

   nano ~/.bashrc

在文件末尾添加以下内容（以 Hugging Face 和 PyTorch 为例，其余变量同理）：

   export HF_HOME=/data/models/huggingface
   export TRANSFORMERS_CACHE=$HF_HOME
   export TORCH_HOME=/data/models/torch

保存退出（nano 按 Ctrl+O 回车，Ctrl+X）。
使配置立即生效：

   source ~/.bashrc

注意： 如果使用 zsh，对应文件是 ~/.zshrc，操作步骤完全一样。

系统级永久设置：修改 /etc/environment

系统级设置对所有用户生效，适合服务器多用户场景。
注意 /etc/environment 不支持变量引用，必须写成绝对路径。

编辑系统环境变量文件：

   sudo nano /etc/environment

添加如下行（不要使用 $ 或变量嵌套）：

   HF_HOME=/data/models/huggingface
   TRANSFORMERS_CACHE=/data/models/huggingface
   TORCH_HOME=/data/models/torch

保存退出后，重启系统或重新登录才能使变量生效。如果不想重启，可以手动导出一次：

   export $(cat /etc/environment | xargs)

避坑指南与常见问题

变量名大小写敏感： Hugging Face 官方推荐的变量是 HF_HOME，而 HF_HUB_CACHE 同样有效，建议以官方文档为准。
source 只影响当前终端： 执行后只对当前 Shell 窗口生效，新打开的窗口会自动读取配置文件（前提是配置正确）。
路径权限： 如果目标目录是非用户主目录（如 /data/），需要确保用户或进程有读写权限。可使用 chown -R $USER:$USER /data/models 授权。
程序不读取配置： 某些工具（如 huggingface_hub）会优先检查环境变量，如果未设置则回到默认缓存。请在 Python 中运行 import os; print(os.environ.get('HF_HOME')) 确认变量是否传递。

效果验证

运行以下命令检查变量是否被正确读取：

echo $HF_HOME
echo $TRANSFORMERS_CACHE

然后测试模型下载是否写到了新路径。
例如使用 Hugging Face 下载一个小模型：

pip install huggingface_hub
python -c "from huggingface_hub import snapshot_download; snapshot_download('bert-base-uncased')"

查看 /data/models/huggingface 目录下是否出现了 hub 或 models--bert-base-uncased 文件夹。

常见问题解答

问：重启后环境变量丢失怎么办？
答：检查你编辑的是否为 ~/.bashrc（而不是 ~/.bash_profile），并确认 .bashrc 是否被正常加载。某些系统会优先读取 ~/.bash_profile，你可以在其中添加一行 source ~/.bashrc 来确保配置被加载。

问：系统级配置和用户级配置冲突时哪个优先级高？
答：用户级配置（如 ~/.bashrc）优先级高于 /etc/environment，因为 Shell 在启动时后加载用户级文件。

问：变量名比如 HF_HOME 和 TRANSFORMERS_CACHE 必须同时设置吗？
答：不一定。Hugging Face Hub 默认使用 HF_HOME，而 transformers 库还看 TRANSFORMERS_CACHE。建议至少设置 HF_HOME，大多数新版本工具会继承该目录。

问：有没有不重启、不重新登录就全局生效的方法？
答：可以临时导出一次变量（如上文提到的 export），但只有编辑配置文件并重启系统或重新登录才能实现真正的永久生效。如果你不想影响生产环境，请先在一台测试机上演练。

如果你在服务器上操作且担心空间不足，建议先使用 df -h 查看磁盘挂载情况，再决定目标路径。
另外，购买云服务器时选择自带大容量数据盘的方案（如泽御云等正规服务商提供的数据盘挂载服务）可以从硬件层面规避存储瓶颈。

配置开机自启服务重启自动恢复中转服务

定期扫描Docker镜像漏洞排查后门风险