企业官网建设流程全解析

spotDL 完整教程：3 条命令把 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 是一个免费开源的命令行工具，它会自动在 YouTube 等平台上找到你 Spotify 歌曲或歌单的对应音源，并把音频、专辑封面、歌词和元数据一次性下载到本地，让你把整个歌单变成真正属于自己的音乐库。

🎯 为什么值得用 spotDL

• 一个链接搞定一切：粘贴 Spotify 歌曲、专辑、艺人或歌单链接，找歌、下载、填封面、写元数据全自动。
• 元数据开箱即用：下载完的文件自带标题、艺人、专辑名和封面，扔进任何音乐播放器都能正常显示。
• 匹配准确：内置相似度算法会自动过滤 live、cover、remix、slowed 等版本，减少"下错歌"。
• 音源可切换：支持 YouTube、YouTube Music、SoundCloud、Bandcamp 等多个音频源，可配置多个作为后备。
• 不止命令行：内置 Web 界面，不习惯敲命令的人也能在浏览器里搜索下载。

🚀 三步快速上手

第一步：环境准备

• Python 3.10 ~ 3.14（Windows 安装时记得勾选 "Add to PATH"）
• FFmpeg 4.2 或更高版本（下一步可以让 spotDL 自己下载，不用手动装）
• 无需显卡，普通电脑、NAS、服务器都能跑

第二步：安装

1. 打开终端，运行pip install spotdl（macOS / Linux 若提示找不到命令，换成pip3）
2. 运行spotdl --download-ffmpeg，让 spotDL 把 FFmpeg 装到自己的工作目录
3. 运行spotdl --download-deno安装 Deno（强烈建议，缺了它部分 YouTube 视频会下载失败）

不想用 pip 的话，也可以克隆源码构建：git clone https://gitcode.com/GitHub_Trending/sp/spotify-downloader进入目录后执行pip install uv、uv sync、uv run scripts/build.py，可执行文件会生成在dist/里。

第三步：首次运行

先cd到你希望存放歌曲的目录（文件会下载到当前目录），然后：

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

几分钟后，当前目录里就会出现一首带封面、带标签的 MP3。恭喜，你已经会用 spotDL 了。

🎵 功能巡礼：按输入方式分组

粘贴 Spotify 链接（最常用的方式）

歌曲、专辑、艺人、歌单链接都直接支持，同一行可以用空格堆叠多个任务排队下载：

spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID spotdl download 'The Weeknd - Blinding Lights' https://open.spotify.com/album/4yP0hdKOZPNshxUOjY0cZj

文字搜索下载

没有链接也没关系，直接用引号包一个搜索词：

spotdl download 'The Weeknd - Blinding Lights'

想搜专辑、歌单、艺人时加上前缀，结果会更准：'album:专辑名'、'playlist:歌单名'、'artist:艺人名'。

下载你账号里的收藏（需登录）

加上--user-auth完成一次 OAuth 登录后，就能批量拿自己的数据：

spotdl download saved --user-auth # 所有红心歌曲 spotdl download all-user-playlists --user-auth # 我创建的全部歌单 spotdl download all-user-saved-albums --user-auth # 我收藏的全部专辑

手动指定音源：YouTube 链接 + Spotify 元数据

自动匹配偶尔失手时，你可以手动指定"音频用这个 YouTube 视频，元数据用这首 Spotify 歌"，两个链接用|连接：

spotdl download "https://www.youtube.com/watch?v=XXYlFuWEuKI|https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b"

浏览器操作：Web 界面

运行spotdl web后打开http://localhost:8800，即可在网页里搜索歌曲、查看下载列表和进度：

界面源码在 spotdl/web/，目前主要面向单曲下载，批量任务还是命令行更顺手。

歌单同步：让本地库跟着线上歌单走

# 首次：生成同步文件（文件名必须以 .spotdl 结尾） spotdl sync https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID --save-file the-weeknd.sync.spotdl # 之后：随时执行，新歌自动下载、被删的歌自动移除 spotdl sync the-weeknd.sync.spotdl

加上--sync-without-deleting可以只补新不删除。

先存元数据，以后再下载

spotdl save [query] --save-file my-list.spotdl --preload

--preload会提前解析好下载链接，之后正式下载时速度明显更快。

🎬 实战场景

场景一：把 300 首歌的歌单一次性搬进本地播放器

需求：换了一款支持本地曲库的播放器，想把整个歌单连同封面迁过去。

解决方案：一条命令下载歌单，同时生成 m3u 播放列表方便播放器导入：

spotdl download https://open.spotify.com/playlist/XXXX --threads 8 --m3u

关键参数：--threads 8提高并行下载速度；--m3u自动生成播放列表文件；默认 MP3 格式兼容性最好。

场景二：本地收藏长期跟 Spotify 保持同步

需求：每周往歌单加新单曲，希望电脑里的曲库自动跟上。

解决方案：用sync操作，首次生成.spotdl同步文件，之后定期（手动或定时任务）执行一次即可。

关键参数：同步文件路径--save-file my.sync.spotdl；不想删歌时加--sync-without-deleting。

场景三：用 YouTube Music Premium 拿到 256kbps 高音质

需求：默认 128kbps 不够听，想用 Premium 账号的 256kbps 源。

解决方案：在 YouTube Music 设置里把音质调到最高 → 用浏览器插件导出cookies.txt→ 下载时带上 cookie 文件并跳过转码。

spotdl download [query] --cookie-file cookies.txt --format m4a --bitrate disable

关键参数：--format m4a（或opus）+--bitrate disable保留原始高码率文件，避免二次压缩。

🛠️ 调优与排错

下载速度

• --threads调整并行线程数，默认 4，宽带环境可调到 8
• 长歌单先用save --preload预解析链接，正式下载会快一截

音频质量

• 普通账号上限 128kbps；有 YouTube Music Premium 时走上面场景三的方案可到 256kbps
• --format支持 mp3 / flac / ogg / opus / m4a / wav，--bitrate可指定码率或设disable不转码

匹配与常见报错

• 下错歌或漏歌：加--only-verified-results只取高可信结果，或临时--dont-filter-results看看原始匹配
• 'spotdl' is not recognized：Python 没加进 PATH，重装时勾选 "Add to PATH"
• YT-DLP download error：基本是缺 Deno，运行spotdl --download-deno
• HTTP Error 404、RecursionError之类：先升级，pip install -U spotdl
• 更多问题参考官方 docs/troubleshooting.md，完整参数说明见 docs/usage.md

📋 速查表

常用命令

高频参数

文件位置

• 配置文件：Windows 在C:\Users\用户\.spotdl\config.json，Linux 在~/.config/spotdl/config.json，运行spotdl --generate-config可重新生成
• 下载文件：始终保存在你运行命令时的当前目录
• 默认输出命名：{artists} - {title}.{output-ext}，可用--output改
• 音频源与歌词源的源码分别在 spotdl/providers/audio/ 和 spotdl/providers/lyrics/，想换源可以从这里入手

写在最后

从第一条spotdl download开始，到你的整个 Spotify 收藏变成离线可用的本地音乐库，中间只有几行命令的距离。挑一个最近想听歌单试一次，再慢慢加同步、m3u 和高音质这些进阶玩法——你的离线曲库会自己长起来。

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