首页/文章/系统折腾

Linux XDG 用户目录与应用数据目录

太阳作者太阳
原创内容采用 CC-4.0 协议发布，转载请注明出处
Linux环境变量

原笔记只有几段环境变量片段，没有留下测试输出。这里把范围收窄到用户级目录变量：配置文件、应用数据、缓存和运行时状态各自放到稳定的位置，避免把机器专属路径硬编码进脚本。XDG Base Directory Specification要求这些变量使用绝对路径，并规定未设置时的默认目录。

XDG 用户目录

在 ~/.profile 或登录 shell 使用的初始化文件中加入：

export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
export XDG_DATA_HOME="${XDG_DATA_HOME:-$HOME/.local/share}"
export XDG_STATE_HOME="${XDG_STATE_HOME:-$HOME/.local/state}"
export XDG_CACHE_HOME="${XDG_CACHE_HOME:-$HOME/.cache}"

变量值必须是绝对路径；保留已有值可以避免覆盖桌面环境或发行版已经设置的目录。创建目录并检查结果：

mkdir -p "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME"
printf '%s\n' "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME"

配置放在 XDG_CONFIG_HOME，应用的持久数据放在 XDG_DATA_HOME，可删除的缓存放在 XDG_CACHE_HOME；需要跨重启保留但不属于配置的数据可以放在 XDG_STATE_HOME。不要把密钥或 token 放进公开的 shell 配置示例。

桌面用户目录

XDG Base Directory 变量描述应用目录；桌面的“下载”“文档”等用户目录由 xdg-user-dirs 管理，配置文件通常是 $XDG_CONFIG_HOME/user-dirs.dirs。安装工具后可以生成或更新目录：

sudo apt install xdg-user-dirs
xdg-user-dirs-update
xdg-user-dir DOWNLOAD
xdg-user-dir DOCUMENTS

user-dirs.dirs 可以写成下面这样的完整用户目录配置，路径相对于 home 展开：

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_VIDEOS_DIR="$HOME/Videos"

原记录采用小写目录名；如果要延续这套布局，可以把八项改成：

XDG_DESKTOP_DIR="$HOME/desktop/"
XDG_DOWNLOAD_DIR="$HOME/download/"
XDG_TEMPLATES_DIR="$HOME/templates/"
XDG_PUBLICSHARE_DIR="$HOME/public/"
XDG_DOCUMENTS_DIR="$HOME/documents/"
XDG_MUSIC_DIR="$HOME/music/"
XDG_PICTURES_DIR="$HOME/pictures/"
XDG_VIDEOS_DIR="$HOME/videos/"

也可以用命令写入一个具体目录，再重新生成用户目录：

xdg-user-dirs-update --set DOWNLOAD "$HOME/Downloads"
xdg-user-dirs-update --set DOCUMENTS "$HOME/Documents"
xdg-user-dirs-update
xdg-user-dir DOWNLOAD

xdg-user-dirs 官方项目说明，xdg-user-dirs-update 会根据配置和当前 home 更新这些目录；xdg-user-dir DOWNLOAD 返回具体目录路径。应用数据目录和桌面用户目录解决的是两类问题，不要用 XDG_DOWNLOAD_DIR 替代 XDG_DATA_HOME。

让应用实际使用这些目录

环境变量只对读取它们的应用生效。修改 ~/.profile 后重新登录，或在当前 shell 显式加载：

. "$HOME/.profile"
printf 'config=%s\ndata=%s\nstate=%s\ncache=%s\n' \
  "$XDG_CONFIG_HOME" "$XDG_DATA_HOME" "$XDG_STATE_HOME" "$XDG_CACHE_HOME"

服务管理器、桌面启动器和非交互 shell 可能使用不同的环境来源；遇到“终端有效、服务无效”时，检查服务的 Environment、启动器配置和实际进程环境，不要只检查交互式 shell。

Hugging Face 镜像变量

原笔记中的 Hugging Face 片段保留为独立用法：

export HF_ENDPOINT=https://hf-mirror.com

HF_ENDPOINT 是第三方镜像地址，是否可用、是否满足数据与认证要求取决于当前网络和镜像运营方。它不是 XDG 标准，也不应写进所有机器的全局环境。若使用 huggingface_hub，优先查看其官方环境变量文档；例如 HF_HOME 会影响 token 与缓存目录。secret、访问 token 和私有端点应通过本机安全存储或服务 secret 注入。

排查顺序

env | rg '^XDG_(CONFIG|DATA|STATE|CACHE)_HOME='
printf 'HF_ENDPOINT=%s\n' "${HF_ENDPOINT:+已设置}"
command -v bash

如果变量为空，检查初始化文件是否被当前 shell 读取；如果目录不生效，确认应用是否支持 XDG 规范以及变量是否在应用启动前已经存在。