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-downloaderspotDL 是一款开源的命令行音乐下载工具给它一个 Spotify 歌曲或歌单链接它会在 YouTube 上检索匹配曲目连同专辑封面、歌词和元数据一并保存为本地文件。这篇使用教程面向想把线上歌单转为本地曲库的个人用户读完你可以完成 pip 安装、跑通首次下载并掌握 sync 同步、save 元数据导出等进阶操作。环境要求与首次安装运行 spotDL 前先确认本机满足以下条件Python 3.10–3.14且已加入 PATHFFmpeg 4.2 或更高版本且已加入 PATHWindows 用户需先安装 Visual C 2019 运行库macOS/Linux 下把命令中的pip换成pip3安装分三步pip install spotdl spotdl --download-ffmpeg spotdl --download-deno第一条安装主程序后两条分别把 FFmpeg 和 Deno 下载到 spotDL 自己的安装目录不必再动系统环境。如果你打算在系统层面使用 FFmpeg也可以改用brew install ffmpegmacOS或发行版包管理器Linux自行安装。Deno 强烈建议装spotDL 底层用 yt-dlp 从 YouTube 取音源部分视频必须依赖 Deno 才能下载成功缺失时带 made for kids 标记的内容会直接失败。装完后执行spotdl -h查看全部选项。除 pip 外还有几条替代路径从 Releases 页下载预编译可执行文件双击不带参数启动时默认打开 Web UI、Termux 安装脚本、Arch 的 AUR 包以及 Docker 镜像。Docker 方式适合服务器场景docker build -t spotdl . docker run --rm -v $(pwd):/music spotdl download [trackUrl]用 Compose 部署时建议设置PUID/PGID环境变量让容器自动处理文件权限下载内容存放在命名卷spotdl_music:/music。第一次下载最小路径跑通spotDL 的输出目录就是当前工作目录——你从哪里运行命令文件就落在哪里。所以下载前先cd到希望存放音乐的文件夹Windows 可在文件夹内 SHIFT右键打开 PowerShell。最小用法只有一行spotdl [urls]默认执行download操作解析链接 → 在 YouTube 检索对应曲目 → 下载最高可用码率的音频 → 写入封面、歌词与元数据。如果spotdl命令无法直接调用改用python -m spotdl [urls]以包的方式运行效果相同。想要图形化操作可以执行spotdl web启动 Web UI适合下载单曲批量歌单、目录同步、元数据修复等完整能力都在命令行。五种操作模式各解决什么问题spotDL 的通用形式是spotdl [operation] [options] QUERYquery 通常是 Spotify URL 列表。各操作的能力、使用时机和注意点如下。download默认能做什么下载音频并嵌入专辑封面、歌词、元数据什么时候用把单曲或整张歌单保存为本地文件注意点输出到当前目录音源质量受账户状态影响见下文save能做什么只抓取 Spotify 侧的元数据并写入.spotdl文件不下载任何音频什么时候用先备份歌单信息、生成清单之后再决定是否取音频关键参数--save-file {filename}.spotdlsync能做什么对比本地目录与歌单当前状态新增的曲目补下、被移除的曲目从目录删除什么时候用本地曲库需要长期跟随在线歌单变化关键参数首次运行spotdl sync [query] --save-file {filename}.spotdl生成同步文件以后只需spotdl sync {filename}.spotdl注意点只处理增删差异不动其他文件url能做什么把 query 中每首 Spotify 歌曲转成人类可读的 URL什么时候用只需要链接清单、不想下载文件web能做什么启动 Web 界面代替命令行什么时候用偶尔下载一两首歌注意点功能有限仅支持单曲下载音源与音频质量spotDL 刻意选择 YouTube 作为音源而不是直接抓取 Spotify以此绕开后者的下载限制。取流时它始终拉取当前账户可用的最高码率普通用户 128 kbpsYouTube Music Premium 用户 256 kbps。各格式与质量的详细对照见 docs/usage.md。需要说明的是用户需自行判断下载行为的合法性项目方不为未获授权的受版权保护内容下载承担责任。场景组合按需求取用整批备份歌单需求把一张歌单完整搬到本地。 配置要点在目标目录直接执行spotdl [playlistUrl]等待默认 download 完成即可。本地曲库长期同步需求歌单每周有增删本地目录要跟着变。 配置要点先spotdl sync [query] --save-file spotdl-sync.spotdl初始化之后每次执行spotdl sync spotdl-sync.spotdl。只要清单不要音频需求先确认歌单内容或只留元数据备查。 配置要点spotdl save [query] --save-file songs.spotdl。只要可读链接需求把 Spotify 链接批量转为可辨识的 URL 交给其他工具。 配置要点spotdl url [query]。服务器/容器部署需求无人值守下载且文件权限要正确。 配置要点用 Docker Compose导出PUID/PGID后再构建运行内容从spotdl_music卷取回。参数速查项目取值 / 说明Python3.10–3.14需在 PATH 中FFmpeg≥ 4.2spotdl --download-ffmpeg可装入 spotDL 目录Deno可选但强烈建议spotdl --download-deno可装入 spotDL 目录音频码率普通 128 kbps / YouTube Music Premium 256 kbps输出位置命令运行的当前目录完整选项spotdl -h常见问题某些歌曲反复下载失败通常是缺 Deno带 made for kids 标记的视频尤其依赖它。先执行spotdl --download-deno再重试。为什么拿到的音质只有 128 kbps这不是 spotDL 的限制而是 YouTube 对普通账户提供的最高档位256 kbps 需要 YouTube Music Premium 账户。文件跑到了意料之外的位置输出目录即命令的启动目录。在目标文件夹里直接打开终端或cd过去再执行即可。Docker 绑定挂载报权限错误宿主目录必须允许容器内UID/GID写入用 Compose 设置PUID/PGID可以让容器替你管理权限。适用边界spotDL 适合个人合法内容的离线保存与曲库管理不适用于绕过付费订阅批量抓取。下一步建议先跑通一次完整歌单下载再按需尝试 sync 与 meta 操作更多音频格式选项参考 docs/usage.md。【免费下载链接】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），仅供参考