spotDL Spotify 音乐下载完全指南：5 分钟把播放列表保存到本地
【免费下载链接】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
飞机上断了信号，我打开 Spotify 里的旅行歌单，播放就此中断——这是不少人遇到过的情景。spotDL 是一个开源命令行工具，能把 Spotify 的播放列表、专辑和单曲下载成本地 MP3 文件，并自动附上专辑封面、歌词与元数据。本文带你把它装好、用起来，并避开常见的坑。
spotDL 是如何找到并下载对应歌曲的 🔍
整个流程很像图书管理员按 ISBN 找书。你交给它一个 Spotify 链接，它先向 Spotify API 查询歌单里每首歌的"书号"——歌名、歌手、专辑、音轨号、时长；然后拿着这些信息去 YouTube、YouTube Music 等音频源搜索对应歌曲；找到匹配项后下载音频，用 FFmpeg 转成 MP3，最后把封面图、发行年份、流派、作曲者等元数据写进文件，并到 Genius、Musixmatch 等来源检索歌词附上，还可以生成支持逐行显示的歌词文件。
相比"存下视频再删掉"的做法，这条"查编号、找书、贴标签再交付"的链路输出的是一份封面、作者、出版年份齐全的文件，放进任何音乐播放器都能被正常管理，封面和曲目顺序都能正确显示。仓库里音源也是模块化的：音频与歌词 provider 都放在 spotdl/providers/ 目录下作为独立模块，默认源找不到歌时，可以在配置文件里追加其他来源重试。
安装 spotDL：5 分钟跑通第一次下载 🚀
环境要求不复杂：Python 3.10 及以上（官方推荐 3.10–3.14），外加 spotDL 要调用的 FFmpeg。Windows 上安装 Python 时记得勾选 "Add Python to PATH"，后面不少"找不到命令"的问题都出在这一步。
- 安装 spotDL：
pip install spotdl（macOS/Linux 用pip3） - 安装 FFmpeg：
spotdl --download-ffmpeg，会自动下载到 spotDL 安装目录，不用单独配置 - 安装 Deno：
spotdl --download-deno，官方强烈建议。部分视频（例如标记为"made for kids"的内容）缺少它会下载失败 - 验证安装：
spotdl --version，输出版本号即成功
如果安装后spotdl命令不可用，把本文所有命令换成python -m spotdl执行即可。Docker、预编译可执行文件等安装方式详见安装指南。
用 spotDL 下载 Spotify 音乐的三种方式 🎧
不管你有歌单链接、只记得歌名，还是不想碰命令行，spotDL 都有对应入口。注意：下载的文件会落在你打开终端的那个文件夹里，建议先 cd 到目标目录。
整张 Spotify 播放列表下载，备好离线音乐
长途旅行前，把整个旅行歌单带离平台。复制播放列表链接后执行：
spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGIDspotDL 会依次解析每一首歌、搜索匹配并下载，终端中显示进度。完成后当前目录里是一整套 MP3，每首都带封面和元数据，同步到手机或播放器就能全程离线听。专辑、艺人、单曲链接用法完全相同，只是 URL 不同；一次想下多个任务，用空格把链接隔开依次排队即可。
没有链接，直接搜索并下载歌曲
只记得歌名时，把搜索词用单引号包起来：
spotdl download 'The Weeknd - Blinding Lights'
spotDL 会在音源里搜索对应歌曲并下载、补全元数据。搜索词加album:或playlist:前缀可以精确到专辑和播放列表，例如spotdl download 'album:21'。如果自动匹配选错了版本，还能手动指定：把 YouTube 链接和 Spotify 链接写成"YouTubeURL|SpotifyURL"的格式一起传入。更多查询写法见使用文档。
在网页界面里搜索并下载歌曲
命令行不熟，或者只想下两三首时，网页界面更直观。运行下面命令，然后在浏览器打开 http://localhost:8800 ：
spotdl web图：在 spotDL 网页界面搜索"Electro-Light"，结果带歌曲封面与歌手信息，点右侧绿色按钮即可下载
每条搜索结果都带封面、歌名和歌手，点右侧的下载按钮就开始下载，界面右上角还有设置入口。注意网页版目前只支持单曲下载，播放列表和整张专辑仍建议走命令行。
进阶与避坑：自定义参数与报错解决 ⚙️
自定义输出目录、命名规则与播放列表同步
默认文件名为"歌手 - 歌名.mp3"，落在当前目录。用--output可以控制目录结构，例如spotdl --output "{artist}/{album}/{title}.{output-ext}" download [链接]会按"歌手/专辑/歌名"组织文件，模板还支持 {year}、{track-number}、{genre} 等变量。音频格式用--format选择 mp3、m4a、opus 等，码率用--bitrate控制；再加--m3u可以生成播放列表文件，方便支持 m3u 的播放器整单播放。长期使用建议运行spotdl --generate-config生成配置文件，Linux 下位于 ~/.config/spotdl/config.json，Windows 下在 C:\Users\用户名.spotdl\config.json，文件会自动加载，以上选项都可以写进去，不用每次敲命令。
对于经常变动的歌单，用 sync 命令保持本地与 Spotify 同步——新歌自动补下，删掉的歌自动清理：
spotdl sync https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID --save-file "travel.spotdl" spotdl sync travel.spotdl第一条创建同步文件，第二条以后每次执行它就完成增量同步。
遇到报错，先查这四个地方
如果提示'spotdl' is not recognized或command not found，说明 PATH 没配好，重装 Python 时勾选 Add to PATH，或直接用python -m spotdl运行。如果出现AudioProviderError: YT-DLP download error，多半是缺 Deno，执行spotdl --download-deno装上再试。如果报pkg_resources.DistributionNotFound，是 yt-dlp 的依赖没装全，用pip install -U brotli websockets yt-dlp补齐。如果提示HTTP Error 404，一般是版本过旧，执行pip install -U spotdl升级。更多报错对照可查故障排查指南。
spotDL 把"从 Spotify 链接到带封面、带元数据、即下即听本地文件"这件事压缩成了一条命令。想查看源码或跟进后续更新，可以先克隆仓库：
git clone https://gitcode.com/GitHub_Trending/sp/spotify-downloader【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
