spotDL 音乐下载环境搭建：两个依赖与三种装法

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

spotDL 是一个开源命令行工具，能把 Spotify 的歌单、专辑、单曲连同专辑封面与元数据一起存到本地，音频从 YouTube 等源匹配而来。下文按「先看结果、再备环境、最后自检」的顺序完成部署，装完用一条命令即可跑通验证。

🎯 装好之后你能拿到什么

装好后 spotDL 有两种用法：在终端执行spotdl web，或双击预编译可执行文件，都会打开一个网页版控制台，用于搜索、下达下载任务并查看进度；直接在终端运行spotdl download <Spotify链接>，则能下载单曲、专辑、整张歌单甚至某位艺人。文件默认落在命令所在目录，MP3 里已写入标题、艺人、封面等信息。

🔍 从最终命令倒推依赖清单

你最终只跑spotdl download一条命令，但这条命令背后依赖三个外部组件：

Windows 用户另需安装 Visual C++ 2019 运行时。完整前置条件可查 安装文档。

📦 安装 spotDL 的三条路线

pip 部署 Windows 环境

在 PowerShell 中执行，预期先看到 pip 输出Successfully installed，随后 FFmpeg 被拉入 spotdl 安装目录：

pip install spotdl spotdl --download-ffmpeg

若pip未被识别，改用python -m pip install spotdl，或重装 Python 时勾选 "Add to PATH"。不想装 Python 也可以：从项目发布页下载 Windows 可执行文件，双击即进入网页界面。

pip 部署 macOS 与 Linux

流程与 Windows 一致，只是把pip换成pip3，预期输出相同：

pip3 install spotdl spotdl --download-ffmpeg

容器化部署 spotDL

仓库自带 docker-compose.yml。先把 PUID/PGID 设为当前用户 ID，避免挂载目录权限报错，预期歌曲文件落入命名卷spotdl_music：

export PUID=$(id -u) export PGID=$(id -g) docker compose build docker compose run --rm spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b

取回文件时先执行docker compose up --no-start spotdl，再用docker compose cp spotdl:/music/. ./downloads/把卷内文件复制到本地目录。

✅ 安装后的自检测试

先确认工具链可用，预期打印出版本号：

spotdl --version

再跑最短的一条下载，产物留在命令所在目录：

spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b

几分钟后该目录出现一首带完整元数据和封面的 MP3，即达到最小可用状态。

报错时建议按"先修复、再对号入座"的方式处理：

① 下载个别视频时报AudioProviderError: YT-DLP download error

修复：

spotdl --download-deno

现象多出现在标记为儿童内容的视频上。原因是 spotDL 借 yt-dlp 抓取 YouTube 音频，部分视频需要 Deno 运行时解析，而它不在默认安装范围内。

②'spotdl' is not recognized或spotdl: command not found

修复：Windows 重装 Python 并勾选 "Add to PATH"（或手动把 Python 的Scripts目录加入系统 Path 后重开终端）；macOS/Linux 将 bin 目录写入 shell 配置并重新加载：

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc

根因是 Python 的可执行目录没进入系统搜索路径——程序其实已装好，只是终端找不到入口。

③ 下载时抛出KeyError: "Unable to find 'header' ..."

修复：

pip install -U ytmusicapi

根因是 YouTube Music 接口响应结构偶发变化，旧版 ytmusicapi 解析不了；若升级后仍偶发，可等待几分钟再试，无效则执行pip install -U --force spotdl重装。

📚 进阶配置与合规边界

需要调整输出格式（mp3/m4a/opus）、码率、文件名模板或生成 m3u 时，见 使用文档；执行spotdl --generate-config可生成一份默认配置文件供修改（Linux 位于~/.config/spotdl/config.json，Windows 在用户目录下的.spotdl）。其余报错对照 故障排除文档 逐条排查。

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