Spotify歌单本地化最短路径：spotDL 30分钟上手
【免费下载链接】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 歌单，去 YouTube 匹配歌曲，连同专辑封面和元数据一起下载成本地 MP3。你只需要粘贴一个链接。
🚀 先拿到一首歌，看到一次成功
前置条件：装好 Python 3.10 以上。Windows 用户还需要装 VC++ 2019 运行库。然后按顺序执行三条命令。
先用 pip 安装 spotDL。如果系统提示找不到 pip，把命令里的 pip 换成 pip3 即可：
pip install spotdl装完直接得到spotdl命令行工具，这是官方推荐的安装方式。
spotDL 转码依赖 FFmpeg。不建议装到系统里，让它放进自己的目录最省事：
spotdl --download-ffmpeg这条命令把 FFmpeg 下载到 spotDL 的安装目录，不污染系统环境。
最后进入你希望存放文件的文件夹，下载一首歌：
spotdl download https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b下载位置就是你运行命令时的当前目录，所以要先cd到目标文件夹。
打开那个文件夹，能看到一首“歌手 - 歌名”命名的 MP3，封面和标签都已嵌入。到这里就算跑通了。
打开网页界面，点着下载
不想记命令，就用 Web 界面。在终端里运行这条命令启动服务：
spotdl web浏览器会自动打开 http://localhost:8800 。8800 是默认端口，想换端口加--port参数。
之后的操作分四步：
- 在搜索框粘贴歌曲链接，或直接输入歌名加歌手名。
- 在结果卡片上点下载图标。
- 等进度条走完，下载完会自动嵌入元数据。
- 文件默认存在会话目录里。想让它落到当前文件夹，启动命令后加
--web-use-output-dir。
提醒一句：Web 界面适合单曲下载。批量处理整个歌单，还是用下面的命令行。
用一条命令搬走整个歌单
日常批量使用，命令行才是主场。按这四步走：
- 拿到歌单链接。在 Spotify 客户端右键歌单，选“分享”再“复制链接”。
cd进你想存文件的文件夹。下载位置由这一步决定。- 执行下载：
spotdl download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID专辑和艺人链接同理，把 URL 换掉就行。
- 长歌单建议追加
--print-errors。结束时它会打印一份失败清单，方便你补漏。
想顺带生成播放列表文件，再加--m3u。完成后会多出一个 m3u8，播放器可以直接导入。
把下载流程固定进容器
想在多台机器上得到完全一致的环境，或者把流程交给同事，用 Docker 最稳。一行命令：
docker run --rm -v $(pwd):/music spotdl/spotify-downloader download <歌曲URL>-v $(pwd):/music把当前文件夹映射进容器。MP3 直接落在你眼前的目录里。--rm让容器用完即删，不留残留。
如果偏好 Compose 方式管理权限，仓库里自带docker-compose.yml，效果等价，不展开。
🧩 升级下载工作流的三个动作
让本地文件和歌单保持同步
歌单每周更新，手动对照很麻烦。用 sync 命令，按顺序执行两行：
spotdl sync https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID --save-file "mylist.sync.spotdl" spotdl sync "mylist.sync.spotdl"第一行下载歌曲并生成一个基线文件，文件名必须以.spotdl结尾。第二行按基线做增量：新歌自动补下，被移除的歌自动清掉。担心误删就加--sync-without-deleting。
自定义文件的命名格式
--output支持变量，默认格式是“歌手 - 歌名.mp3”。想加年份可以这样写：
spotdl download <URL> --output "{artist} - {title} ({year}).{output-ext}"常用变量一览：
| 变量 | 作用 | 示例 |
|---|---|---|
| {title} | 歌曲名 | Blinding Lights |
| {artist} | 主唱歌手 | The Weeknd |
| {album} | 所属专辑 | After Hours |
| {year} | 发行年份 | 2020 |
| {track-number} | 专辑内序号 | 03 |
| {output-ext} | 文件扩展名 | mp3 |
提升音质上限
默认输出 128kbps 的 MP3。如果你有 YouTube Music Premium，能拿到 256kbps 的 M4A。
| 参数 | 作用 | 示例 |
|---|---|---|
| --cookie-file | 指定 YT Music 登录 cookies 文件 | --cookie-file cookies.txt |
| --format | 输出格式 | --format m4a |
| --bitrate | 目标码率，disable 表示不转码 | --bitrate disable |
| --threads | 并发下载线程数 | --threads 8 |
操作顺序：先把 YT Music 的音质设置调到最高，导出 cookies.txt，再把参数拼进下载命令。没有 Premium 就别硬加--bitrate 320k。它只是把文件重新转得更大，音质不会变。
🕳️ 避开四个最常见的坑
1. 提示spotdl不是内部或外部命令
终端报“未识别”或 command not found。原因是 Python 安装目录没进 PATH，Windows 安装时漏勾了 Add to PATH。重装 Python 并勾选该选项，或改用python -m spotdl运行。
2. 启动即报 FFmpeg is not installed
命令一执行就中断，提示找不到 FFmpeg。spotDL 需要它转码和写标签，而你只装了 spotdl 本体。执行一次spotdl --download-ffmpeg就能解决。
3. 个别歌曲报 YT-DLP download error
错误信息是 AudioProviderError。部分视频需要 Deno 才能抓取，标记为儿童向的视频尤其明显。执行spotdl --download-deno补装即可。
4. 歌下到了意料之外的文件夹
MP3 没出现在你期望的目录里。下载位置永远跟着命令运行时的“当前工作目录”走。Windows 下可以按住 Shift 再右键目标文件夹，从菜单里打开 PowerShell 窗口，再执行命令。
下一步去哪找答案
- 想看全部命令行参数和输出变量，打开 docs/usage.md。
- 报错时直接查 docs/troubleshooting.md，按错误信息组织，对号入座。
- 想批量改默认行为，执行
spotdl --generate-config生成配置文件。Linux 下位于~/.config/spotdl/config.json。 - 更深的问题去项目官方 Discord 社区提问，邀请链接写在仓库 README 里。
【免费下载链接】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），仅供参考
