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-downloaderspotDL 是一个命令行音乐下载工具负责把 Spotify 歌单和专辑里的曲目在 YouTube 上匹配音源连同封面、歌词与 ID3 元数据一起下载成本地文件。它解决的核心问题很具体把你流媒体账号里的歌单变成可以离线播放、可导入 NAS 或 DAP 播放器的本地曲库。关键硬性指标Python 3.10–3.14FFmpeg 4.2 以上无 GPU 或显存要求纯 CPU 环境即可跑音源固定走 YouTube普通账号最高 128 kbps。装好 CLI 并验证能跑安装只涉及 Python 包加两个运行时依赖全部可以在终端内完成pip install spotdl安装主程序这是官方推荐方式更新时执行pip install --upgrade spotdl。spotdl --download-ffmpeg把 FFmpeg 自动装到 spotDL 所在目录不用改系统全局环境。spotdl --download-deno安装 Deno部分视频包括标记为儿童向的内容没有它会直接下载失败。spotdl --generate-config在~/.config/spotdl/config.jsonLinux 路径生成一份配置文件把常用参数固化下来之后每次自动加载。spotdl web启动 Web 界面验证安装是否成功。用 Web UI 验证安装执行spotdl web后浏览器会自动打开http://localhost:8800端口和主机名可用--port、--host覆盖在搜索框输入歌名即可预览封面和匹配结果右侧绿色按钮直接下单歌下载。注意两点Web 模式功能有限只支持单曲下载批量还是走 CLI默认情况下文件写入临时会话目录程序退出即清理想落盘到--output指定目录需加--web-use-output-dir。如果不想在宿主机装 Python 环境也可以用仓库根目录现成的 Dockerfile 和 docker-compose.yml 走容器路线# 克隆仓库并构建镜像 git clone https://gitcode.com/GitHub_Trending/sp/spotify-downloader cd spotify-downloader export PUID$(id -u) export PGID$(id -g) docker compose build这段命令的作用是把源码构建为镜像并用你的系统 UID/GID 创建容器用户避免下载出来的文件归属 root。跑通三类下载场景验证环境可用后下面是三个最典型的使用场景按从单点到批量、再到自动化的顺序展开。把整张歌单批量存成本地 MP3这个场景的产出是一整目录歌手 - 歌名.mp3文件每首带封面内嵌、完整 ID3 标签和歌词文件外加一个 m3u 播放列表。最简命令只传 URL下载目录就是执行 spotdl 的当前目录spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID队列机制允许一条命令塞进多个查询歌单、专辑、搜索词、URL 可以混排顺序无关spotdl download The Weeknd - Blinding Lights https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj参考参数组合生成 m3u 列表并控制输出命名spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID \ --output {artists} - {title}.{output-ext} \ --m3u \ --threads 4 \ --lyrics genius azlyrics说明一下各参数--output的模板变量{album}、{year}、{track-number}等约 20 个完整列表见 docs/usage.md 的 output 变量表--m3u默认生成{list[0]}.m3u8模板里写{list}可以为队列里每个列表各生成一份--threads默认 4控制并发下载与转码线程数。如果自动匹配选错了歌用YouTubeURL|SpotifyURL的竖线语法做手动配对前者提供音源、后者提供元数据spotdl download https://www.youtube.com/watch?vXXYlFuWEuKI|https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b预期产出每首曲目一个带封面的 mp3文件名与--output模板一致同目录多一份 m3u8导入任何播放器都是完整歌单而非散文件。如果整张专辑想保持曲目顺序感追加--playlist-numbering会把歌单名写进专辑标签、歌单封面写入曲绘下载自己账号的收藏曲目则用spotdl download saved --user-auth--user-auth走 Spotify OAuth 登录。让本地曲库与歌单自动对齐批量下完一次只是快照歌单之后还会增删。sync 操作的定位有点像 git pull官方称为 synchronization它只处理差异新增的曲目补下载被移除的曲目从本地删除其余文件不动。初始化时生成一个以.spotdl结尾的同步文件后缀是硬性要求spotdl sync https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID --save-file the-weeknd.sync.spotdl之后每次对齐只需传这个文件不再需要 Spotify URLspotdl sync the-weeknd.sync.spotdl不想真的删文件时加--sync-without-deleting只补新不删旧。另外save操作只保存元数据不落盘音频配合--preload可以先预解析下载链接后续真正下载时省去搜索时间spotdl save The Weeknd - Blinding Lights --save-file the-weeknd.spotdl --preload用 Docker 跑无人值守下载前三步环境都已就绪的话容器场景主要面向定时任务和 NASdocker-compose.yml里定义了命名卷spotdl_music:/music所有下载落在卷里容器可随时销毁重建。跑一条下载任务docker compose run --rm spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b事后从卷里取文件docker compose up --no-start spotdl mkdir -p downloads docker compose cp spotdl:/music/. ./downloads/注意如果改成 bind-mount-v $(pwd):/music而不是命名卷宿主目录必须可被容器内 UID/GID 写入这就是构建时要 exportPUID/PGID的原因。调优参数与高频报错处理调优部分按遇到什么瓶颈用什么手段成对来看。匹配不准下错歌—— 先用--search-query {artists} {title}收紧搜索模板变量与--output相同仍不准就换音源组合--audio youtube-music youtube这类多值写法会按顺序做 fallback仓库内置六个音源含youtube-music、slider-kz、soundcloud、bandcamp等实现位于 spotdl/providers/audio/。最后手段就是前文的YouTubeURL|SpotifyURL手动配对。128 kbps 的音质天花板—— 普通账号下 YouTube 源最高 128 kbps这是音源上限而非 spotdl 限制。有 YouTube Music Premium 的话把music.youtube.com的 cookies 导出再用 M4A/OPUS 格式跳过转码spotdl download [url] --cookie-file cookies.txt --format m4a --bitrate disable--bitrate disable对 M4A/OPUS 意味着直接保留源文件不再二次编码反过来--bitrate高于源音质的值只会增大体积、不提升质量官方文档明确提示过这一点。批量任务失败不可见—— 长歌单跑完不知道哪几首挂了用--print-errors在退出时汇总错误清单或--save-errors errors.txt落盘配合--archive记录已下载曲目重跑时跳过已存在文件的行为由--overwrite skip|metadata|force控制。常见报错按现象 → 根因 → 解法列四个高频项完整清单在 docs/troubleshooting.md现象spotdl is not recognized或spotdl: command not found根因是 PATH 未包含安装目录Linux 下通常是~/.local/bin解法export PATH~/.local/bin:$PATH后source ~/.bashrc。现象AudioProviderError: YT-DLP download error根因是缺 Deno特定视频无法解析解法spotdl --download-deno。现象pkg_resources.DistributionNotFound根因是 yt-dlp 的部分依赖如brotli、websockets没装全解法pip install brotli websockets yt-dlp -U。现象KeyError: header根因是 YouTube Music API 响应结构临时变化解法pip install -U ytmusicapi持续报错再pip install -U --force spotdl。深入源码与文档的路径如果你还想继续往下走仓库内有三个值得看的位置全量 CLI 参数说明、--output/--search-query模板变量表和音频质量细节docs/usage.md各音频与歌词提供商的实现想加 fallback 或看懂匹配逻辑从这里入手spotdl/providers/配置文件的全部键值含 Web 服务端的--enable-tls、--allowed-origins等以spotdl --generate-config生成的~/.config/spotdl/config.json为准结构说明在 docs/usage.md 的 Config file 一节【免费下载链接】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），仅供参考