spotDL Spotify音乐下载完整指南

spotDL Spotify音乐下载完整指南

【免费下载链接】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 找到匹配音频，下载后写入歌名、歌手、封面和歌词。它解决的是 Spotify 音乐无法保存到本地离线收听的问题，适合想建立带完整元数据的离线曲库的人。

装之前先看：它适不适合你

• 适合：想把 Spotify 歌单、收藏歌曲、专辑导出成本地 MP3 离线播放、且能接受命令行操作的人。
• 不适合：只想用图形界面的人——网页版spotdl web只支持单曲下载；想要 Spotify 会员自己的音源的人——spotDL 的音频来自 YouTube、SoundCloud 等，不来自 Spotify 本身。
• 环境门槛：Python 3.10–3.14（需加入 PATH）、FFmpeg 4.2 以上；不需要 GPU，Windows、macOS、Linux、Termux、Docker 均可运行。
• 提示：下载行为的版权责任由使用者自行承担，README 里有明确说明，只导出自己有权使用的音乐。

安装 spotDL 并下载第一首歌

前提是终端里python -V能返回 3.10 及以上版本，然后三条命令完成安装与本地依赖：

pip install spotdl spotdl --download-ffmpeg spotdl --download-deno

第二条把 FFmpeg 下载到 spotdl 目录内，免去系统级配置；第三条安装 Deno，yt-dlp 解析部分视频依赖它，缺了它一些歌曲（含标记为 "made for kids" 的视频）会报错。macOS/Linux 上把pip换成pip3。

如何验证安装成功

运行spotdl --version有版本号即安装成功。再下载一首歌做端到端验证：

spotdl download 'The Weeknd - Blinding Lights'

当前目录出现The Weeknd - Blinding Lights.mp3，播放器里能看到歌名、歌手、封面，说明整条链路通了。注意文件始终落在你执行命令的那个目录里，想存到曲库就先cd过去。

spotDL 能做什么：从单曲到整张歌单

导出歌单：输入 Spotify 歌单链接 → 逐曲在 YouTube 匹配、下载、写入元数据 → 得到一批歌手 - 歌名.mp3，可附带一个.m3u8播放列表文件。

手动配对：输入YouTube链接|Spotify链接格式 → 下载指定 YouTube 音频并套上 Spotify 元数据 → 适合自动匹配选错版本（现场版、翻唱）时使用。

持续同步：spotdl sync先把歌单状态存成.spotdl同步文件，之后对同一文件再执行spotdl sync即补齐新增歌曲、删除已移除歌曲；加--sync-without-deleting只补不删，本地目录就和歌单保持一致。

元数据与歌词：可指定 genius、musixmatch、azlyrics 等歌词源，--generate-lrc额外生成同步歌词；meta操作还能给已有文件补元数据。

网页界面：spotdl web在http://localhost:8800启动本地页面，可以搜索并下载单曲，功能比命令行少。

完整演示：导出整个歌单并生成播放列表

以官方docs/usage.md里的示例歌单链接为例：

spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID \ --m3u --playlist-numbering

准备：完成上面的安装三件套，并cd到曲库目录。--m3u生成与歌单同名的播放列表文件；--playlist-numbering把每首歌的专辑名设为歌单名并写入曲目编号，便于在音乐库软件里归档。

结果判断：结束后当前目录应有一组歌手 - 歌名.mp3和一个.m3u8。随机打开一个 mp3 确认标题、歌手、封面已写入，再用播放器打开.m3u8确认能按顺序播放。

易错点：

• YouTube 上找不到的歌会被静默跳过，长歌单建议加--print-errors，结束时汇总列出没下成的歌。
• 个别视频报AudioProviderError: YT-DLP download error，通常是 Deno 没装，执行spotdl --download-deno。
• 重复执行时已有文件默认跳过（--overwrite skip），想强制重下才用--overwrite force。

常用参数调优：格式、码率与音源

音质上限：普通账号音源最高 128 kbps；有 YouTube Music Premium 的用户导出 cookies.txt 后用--cookie-file传入，并选 m4a/opus 格式可拿到 256 kbps 文件，步骤见docs/usage.md的 "YouTube Music Premium" 一节。

常见报错与解决办法

1. spotdlis not recognized / command not found：Python 或 pip 的 bin 目录不在 PATH。Windows 重装 Python 并勾选 "Add to PATH"（图示见docs/installation.md）；macOS/Linux 把~/.local/bin加进 PATH 后source配置。
2. AudioProviderError: YT-DLP download error：缺 Deno，spotdl --download-deno即可。
3. KeyError: 'header'（YTMusic API 报错）：YouTube Music 响应结构变化所致，pip install -U ytmusicapi升到 1.11.1 以上；仍不行则pip install -U --force spotdl。
4. pkg_resources.DistributionNotFound（提示缺 websockets 或 brotli）：yt-dlp 依赖不完整，pip install -U yt-dlp brotli websockets。
5. HTTP Error 404（取 Spotify 元数据时）：已知 spotipy 问题，pip install -U spotdl升到带修复的版本。

定位与延伸

spotDL 在"命令行音乐下载"这个赛道里，是少数以 Spotify 链接为输入、直接产出带元数据本地曲库的工具：sync 和 save 操作覆盖了曲库的日常更新与归档，但它不追求流媒体音质（无会员上限 128 kbps）。想深入的话，可以读spotdl/providers/目录——音频源和歌词源都是抽象成独立模块的，照着现有实现加一个新音乐源并不复杂。

【免费下载链接】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