企业官网建设流程全解析

spotDL 升级 v4.4.3 后 Linux 配置文件路径在哪里？旧路径如何兼容？

【免费下载链接】spotify-downloaderDownload your Spotify playlists and songs along with album art and metadata (from YouTube if a match is found).项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-downloader

在 Linux 上把 spotDL 升级到 v4.4.3 或更高版本后，配置文件不再放在老位置~/.spotdl/config.json，而是迁移到了 XDG 标准路径~/.config/spotdl/config.json。本文基于项目文档（docs/usage.md、docs/installation.md、docs/troubleshooting.md）说明：升级后配置文件到底在哪里、旧路径下已有的配置如何被继续读取，以及如何确认配置生效。

升级 spotDL 到 v4.4.3 及以上版本

前置条件（来自 docs/installation.md）：Python 3.10 - 3.14（已加入 PATH）、FFmpeg 4.2 或更高版本。非 Windows 系统（如 Linux）执行命令时，把pip换成pip3、python换成python3。

pip install --upgrade spotdl

升级 v4.4.3 时还有一个依赖注意点：v4.4.3 要求 ytmusicapi 最低版本为 v1.11.1。如果遇到KeyError: 'header'这类 YouTube Music API 报错，按 docs/troubleshooting.md 的处理方式升级依赖：

pip install -U ytmusicapi

若报错持续，再强制重装 spotDL：

pip install -U --force spotdl

v4.4.3 之后 Linux 上的配置文件位置

根据 docs/usage.md 的 “Config file location” 一节：

• Windows：C:\Users\user\.spotdl\config.json
• Linux（v4.4.3 起）：~/.config/spotdl/config.json

文档同时注明：v4.4.3 之前，Linux 的默认位置是~/.spotdl/config.json，且当新目录不存在时，旧位置仍会被使用。

路径选择的实际逻辑可以在 get_spotdl_path 中核对，Linux 下按以下顺序解析：

1. ~/.config/spotdl已存在 → 使用新路径；
2. 新路径不存在、但~/.spotdl存在 → 继续使用旧路径（即老用户的配置原地生效，无需手动迁移）；
3. 两个目录都不存在（全新用户）→ 创建并使用~/.config/spotdl。

也就是说，升级后 spotDL 会自动“认得”你在旧路径下的配置，只要新目录没有被创建，旧文件就继续被使用。

确认当前使用的是哪个路径

文档没有提供专门的“打印配置路径”命令，可以按文档描述的行为来核对：

1. 检查两个目录哪个存在：

   ls -d ~/.config/spotdl ~/.spotdl 2>/dev/null

   • 只有~/.spotdl存在：说明你在用旧路径配置（~/.spotdl/config.json），升级后行为不变；
   • ~/.config/spotdl也存在：新路径优先，配置读取的是~/.config/spotdl/config.json；
   • 两个都不存在：下次运行 spotDL 时会创建~/.config/spotdl。

2. 配置文件在已存在的情况下会被自动加载，也可以用--config参数显式指定从配置文件下载歌曲。如果不想让配置自动加载，把配置文件中的load_config改为false：

   { "load_config": false }

重新生成配置文件

如果需要在新路径生成一份默认配置，运行：

spotdl --generate-config

注意文档明确提示：该命令会覆盖已有的配置文件，执行前确认当前配置路径下不需要保留的手改项。生成后可以打开对应路径下的config.json核对内容，默认配置样例见 docs/usage.md 的 “Default config” 一节（包含client_id、audio_providers、output、threads等字段）。

一个文档内不一致的地方

docs/usage.md 中--config参数的帮助文本仍写着“~/.spotdl/config.jsonunder linux”，与同文件 “Config file location” 一节给出的~/.config/spotdl/config.json不一致。判断实际读取位置时，建议以 “Config file location” 一节和 spotdl/utils/config.py 中的get_spotdl_path逻辑为准。

适用范围与限制

• 本路径规则针对 v4.4.3 及以上版本；当前仓库中版本号已推进到 4.5.0（见 spotdl/_version.py），规则同样适用。
• 旧路径兼容是“新目录不存在则回退到旧目录”，并非自动迁移：一旦~/.config/spotdl被创建，读取的将是新路径下的配置，旧路径文件不会被合并过来。如需把旧配置带到新路径，需自行复制文件（仓库文档未提供迁移命令，此处只提示行为差异，不额外给出操作步骤）。

【免费下载链接】spotify-downloaderDownload your Spotify playlists and songs along with album art and metadata (from YouTube if a match is found).项目地址: https://gitcode.com/GitHub_Trending/sp/spotify-downloader