go-music-dl README

The project's README from github.com/guohuiyuan/go-music-dl. As one markdown file: README.md.

Go Music DL

⭐ 如果这个项目正在帮你省时间，欢迎顺手点一个 Star。Star 越多，作者越能确认这个工具确实有人在用，也会更有动力优先修复失效站点、适配新站点和更新版本。

Music Downloader Icon

Go Music DL 是一个音乐搜索与下载工具，支持 Web 界面、TUI 终端 和 桌面应用 三种使用模式。除了单曲搜索与下载外，还支持 歌单搜索 / 解析、歌单分类浏览、我的歌单、专辑搜索 / 解析、整单 / 整专曲目查看与批量处理。你可以在浏览器试听，也可以在终端里批量下载，或使用原生桌面应用享受最佳体验。

🚀 快速开始

桌面应用 (推荐)

最简单的使用方式，下载即用：

  1. 从 Releases 下载 music-dl-desktop-rust.exe 或 music-dl-desktop-go.exe
  2. 解压，双击运行
  3. 享受原生桌面体验！

移动端下载说明：在 Releases 页面可直接下载 Android music-dl_arm64-v8a.apk（推荐）/ music-dl_x86_64.apk / music-dl.apk（无分片兼容包）。Android APK 已内置 ffmpeg 与 ffprobe，本地音乐探测、非 MP3 元数据内嵌和视频渲染无需在手机上额外安装 FFmpeg。iOS 会提供 music-dl-ios-unsigned.ipa 给用户自行签名；如果发布环境配置了证书，也会额外提供已签名的 music-dl-ios.ipa。

Web 模式

./music-dl web

Web 服务默认挂载于 /music 路径下。如需通过反向代理挂载到二级目录，可使用 --base-path 参数：

./music-dl web --base-path /dl

对应的 Nginx 反向代理示例：

location /dl/ {
	proxy_pass http://127.0.0.1:8080;

	proxy_set_header Host $host;
	proxy_set_header X-Real-IP $remote_addr;
	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	proxy_set_header X-Forwarded-Proto $scheme;
}

location = /dl {
	return 301 /dl/;
}

Web 模式默认不要求登录即可搜索、播放、下载、浏览歌单 / 专辑和使用本地歌单等普通功能。只有进入右上角 设置、保存系统设置、管理平台 Cookie、通过扫码登录写入 Cookie 等系统配置操作需要管理员登录。

首次触发系统配置登录时，如果还没有管理员账号，启动终端会打印一次性初始化令牌。打开初始化页后填入该令牌，并设置用户名和至少 6 位密码即可创建管理员账号；之后点击设置或右上角登录按钮会进入登录流程。会话 Cookie 默认保留 7 天，右上角按钮会根据状态切换为登录 / 退出登录；退出后会回到首页，普通功能仍可继续使用。

桌面端和移动端 App 内嵌 Web 服务使用 StartDesktop 启动，仅监听本机 127.0.0.1，并默认关闭 Web 管理员登录流程，避免首次启动时因看不到终端初始化令牌而无法进入应用。

TUI 模式

./music-dl -k "搜索关键词"

Web UI 1 Web UI 2

TUI 1 TUI 2

主要功能

歌单 / 专辑支持

歌单分类与我的歌单

Web 首页的歌单入口旁提供 歌单分类 和 我的歌单：

Web 右上角“设置”可管理各平台 Cookie。支持扫码登录的平台会在 Cookie 输入框右侧显示 扫码 按钮：

本地音乐

Web 端在“我的自制歌单”旁提供 本地音乐 入口，用于管理本地下载目录里的音频文件。下载目录来自 Web 右上角“设置”里的“本地下载目录”，默认是 data/downloads。Android 端建议把本地下载目录设置为 /sdcard/Music，便于系统音乐应用识别。

设置里的 音乐文件名模板 支持 {name}、{artist}、{album}、{source}、{id}、{ext}。未写 {ext} 时会自动追加扩展名；模板中的 / 或 \ 可创建相对子目录。例如本地下载目录为 /app/data，模板为 {artist}/{album}/{name} - {artist}.{ext} 时，会保存到 /app/data/歌手/专辑/歌名 - 歌手.flac 这类路径。歌曲元数据本身包含的斜杠会被安全替换为 _，..、. 等路径穿越段会被忽略。

本地音乐性能优化

结合后端缓存与前端分页，减少重复扫盘 / ffprobe / tag 解析的开销：

Web 下载模式与 FFmpeg

Web 端“设置”里新增了 下载时内嵌元数据（封面/歌词） 开关：

⚠️ 开启内嵌元数据依赖 FFmpeg。未安装 FFmpeg 时，会自动跳过内嵌并返回原始音频。

可先验证 FFmpeg 是否可用：

ffmpeg -version

常见安装方式：

WebDAV 同步

Web 设置里新增了 下载时同步到 WebDAV 开关。开启并填写 WebDAV 地址、用户名、密码和远端目录后，点击“保存到本地目录”或“浏览器下载”时，会把音乐文件同时上传到 WebDAV。密码保存在服务端 data/settings.db，Web 设置接口不会回显密码。

仓库提供本地 Docker WebDAV 测试配置，使用 127.0.0.1，不需要域名：

docker compose -f docker-compose.webdav.yml up -d

测试地址为 http://127.0.0.1:18081/dav，用户名 test，密码 123456。上传目录会映射到本仓库的 data/webdav。

Docker / Release 包里的 FFmpeg 与 ffprobe

ffprobe 属于 FFmpeg 工具集，主要用于本地音乐的时长、码率和标签探测；ffmpeg 主要用于非 MP3 音频的封面/歌词元数据写入。缺少它们不会影响程序启动，也不会阻塞本地音乐列表加载，只会降级相关增强能力。

新增改动（简要）

快速开始

桌面应用模式

桌面应用提供了原生窗口体验，无需打开浏览器即可使用。

特性

Docker 部署

本项目提供了多种 Docker 部署方式。当前默认通过 ./data 目录挂载到容器内 /home/appuser/data，下载文件、配置与收藏数据都会持久化到该目录。

注意：首次运行前必须先创建 data 目录（如 mkdir -p data && chmod 777 data），便于宿主机直接访问下载与配置数据。

1. 生产环境部署（推荐）

项目包含 docker-compose.yml 文件，直接拉取云端预编译镜像，无需在本地构建：

# 拉取最新镜像
docker compose pull

# 后台启动服务
docker compose up -d --remove-orphans

# 或一条命令拉取并启动
docker compose up -d --pull always --remove-orphans

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

浏览器访问 http://localhost:8080。

说明：

2. 开发环境部署（本地构建）

如果您修改了源码，希望在本地通过 Docker 重新构建并测试效果，请使用 docker-compose.dev.yml：

# 强制在本地使用 Dockerfile 进行构建并启动
docker compose -f docker-compose.dev.yml up -d --build --remove-orphans

3. 纯命令行模式 (docker run)

如果不使用 Compose，也可以直接通过命令行运行：

docker run -d --name music-dl \
  -p 8080:8080 \
  -v $(pwd)/data:/home/appuser/data \
  -e TZ=Asia/Shanghai \
  --user 1000:1000 \
  --restart unless-stopped \
  guohuiyuan/go-music-dl:latest \
  ./music-dl web --port 8080 --no-browser

# Windows PowerShell
docker run -d --name music-dl -p 8080:8080 -v ${PWD}/data:/home/appuser/data -e TZ=Asia/Shanghai --user 1000:1000 --restart unless-stopped guohuiyuan/go-music-dl:latest ./music-dl web --port 8080 --no-browser

视频生成相关的“更换封面 / 更换音频 / 更换歌词 / 导出视频”按钮已迁移到 Web 设置中管理，默认关闭，可在网页右上角设置面板中开启。

CLI/TUI 模式

# 搜索
./music-dl -k "周杰伦"

TUI 常用按键：

更多用法：

# 查看帮助
./music-dl -h

# 指定搜索源
./music-dl -k "周杰伦 晴天" -s qq,netease

# 指定下载目录
./music-dl -k "周杰伦" -o ./my_music

# 下载时包含封面和歌词
./music-dl -k "周杰伦" --cover --lyrics

GitHub Actions 自动构建

本项目已配置 GitHub Actions 工作流。当推送代码并打上版本标签（如 v1.0.0）时，会自动触发 .github/workflows/docker.yml，构建跨平台镜像（支持 amd64 和 arm64）并推送到 DockerHub。

Android APK 构建

项目支持通过 Gio 打包 Android APK，输出文件为仓库根目录下的三个 APK：

安装 Android APK 后，建议在 Web 右上角“设置”中把“本地下载目录”改为 /sdcard/Music，这样下载文件会直接进入系统音乐目录。

1. 本地构建 APK（Windows）

前置条件：

执行命令：

cd go-music-dl
package_app.bat

脚本会自动：

若检测到 adb，会打印安装命令，例如：

adb install -r music-dl.apk

2. Release 流程自动构建 APK

.github/workflows/release.yml 中新增了 build-android-apk 任务。发布时会在 windows-latest 环境中：

发布后可在 Releases 下载三个 APK，推荐优先使用 music-dl_arm64-v8a.apk；极个别设备若无法安装/运行，再下载 music-dl.apk（无分片兼容包）。

3. Java 17 与 Build-Tools 版本说明（重点）

高版本（34.0.0 及以上）的 Android Build-Tools 已修复旧版 d8.bat 脚本兼容性问题，可正常配合 Java 17 使用。

如果本地仍有 33.0.0，建议升级并清理旧版本：

"C:\Android\cmdline-tools\latest\bin\sdkmanager.bat" "build-tools;34.0.0"

如果你使用 Android Studio，也可以在 SDK Manager -> SDK Tools 中勾选 Show Package Details，然后安装 34.0.0 及以上版本。

非常关键：请到 C:\Android\build-tools\ 目录下，删除或重命名 33.0.0 旧目录，避免 gogio 优先命中旧版 d8。

完成后再次执行：

cd go-music-dl
package_app.bat

iOS App 构建

项目已提供 iOS 打包脚本：package_ios.sh。

1. 构建环境

2. 执行构建

cd go-music-dl
chmod +x package_ios.sh
export IOS_APP_ID=com.guohuiyuan.musicdl
export IOS_PROVISION_PROFILE=/path/to/profile.mobileprovision
./package_ios.sh

# 只生成给用户自行签名的包
IOS_UNSIGNED_ONLY=1 ./package_ios.sh

脚本会自动：

3. 产物说明

发布后可在 Releases 下载 music-dl-ios-unsigned.ipa；配置签名 secrets 后也会上传 music-dl-ios.ipa。

注意：music-dl-ios-unsigned.ipa 不是可直接安装包，需要用户用自己的证书和 provisioning profile 重签。如果需要 GitHub Actions 自动发布已签名 iOS 包，需要配置 IOS_PROVISION_PROFILE_BASE64、IOS_CERTIFICATE_P12_BASE64 和 IOS_CERTIFICATE_PASSWORD。

如果你 Fork 了本仓库并希望使用自己的构建流：

  1. 在你的仓库 Settings -> Secrets and variables -> Actions 中添加：
  1. 将 docker-compose.yml 中的镜像地址修改为你自己的：image: 你的用户名/go-music-dl:latest

Web 换源说明

单曲卡片里的“换源”会在其它平台里找更像的版本：

当前会跳过 soda 与 fivesing。

每日歌单推荐

Web 页面有“每日推荐”入口，会聚合网易云、QQ、酷狗、酷我。 TUI 在输入界面按 w 直接拉取推荐歌单，然后回车进详情。

支持平台

平台 包名 搜索 下载 歌词 歌曲解析 歌单搜索 歌单推荐 歌单分类 我的歌单 扫码登录 歌单歌曲 歌单链接解析 专辑搜索 专辑歌曲 专辑链接解析 备注
网易云音乐 netease ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 支持 FLAC 无损
QQ 音乐 qq ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 支持 FLAC 无损
酷狗音乐 kugou ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 支持普通歌曲 FLAC 无损
酷我音乐 kuwo ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ❌ ✅ ✅ ✅ ✅ ✅
咪咕音乐 migu ✅ ✅ ✅ ✅ ✅ ❌ ✅ ❌ ❌ ✅ ✅ ✅ ✅ ✅ 歌单歌曲使用 MIGUM3 接口
千千音乐 qianqian ✅ ✅ ✅ ✅ ⚠️ ❌ ✅ ❌ ❌ ✅ ✅ ✅ ✅ ✅ 歌单搜索可能返回空，已知 ID/链接可解析
汽水音乐 soda ✅ ✅ ✅ ✅ ✅ ❌ ❌ ✅ ⚠️ 未调通 ✅ ✅ ✅ ✅ ✅ 音频解密，支持短链和个人歌单；扫码登录暂未调通
5sing fivesing ✅ ✅ ✅ ✅ ✅ ❌ ❌ ❌ ❌ ✅ ✅ ❌ ❌ ❌
Jamendo jamendo ✅ ✅ ✅ ✅ ⚠️ ❌ ❌ ❌ ❌ ✅ ✅ ✅ ✅ ✅ 歌单搜索可能返回空，公开歌单链接可解析
JOOX joox ✅ ✅ ✅ ✅ ✅ ❌ ✅ ❌ ❌ ✅ ✅ ✅ ✅ ✅ 歌单支持 OpenJOOX 接口和网页数据兜底
Bilibili bilibili ✅ ✅ ✅ ✅ ✅ ❌ ❌ ❌ ✅ ✅ ✅ ❌ ❌ ❌ 支持 FLAC 无损
Apple Music apple ✅ ⚠️ ✅ ✅ ✅ ❌ ✅ ❌ ❌ ✅ ✅ ✅ ✅ ✅ 下载仅 preview，完整需 gamdl 解密

⚠️ 表示方法已接入，但平台搜索接口结果不稳定；优先使用已知 ID 或链接解析。

歌曲链接解析

支持直接解析音乐分享链接：

./music-dl -k "[https://music.163.com/#/song?id=123456](https://music.163.com/#/song?id=123456)"

支持解析的平台：网易云、QQ音乐、酷狗、酷我、咪咕、Bilibili、汽水音乐、5sing、Jamendo、JOOX、千千音乐、Apple Music。

歌单链接解析

支持直接解析歌单/合集分享链接：

./music-dl -k "[https://music.163.com/#/playlist?id=123456](https://music.163.com/#/playlist?id=123456)"

支持解析的平台：网易云、QQ音乐、酷狗、酷我、咪咕、Jamendo、JOOX、千千音乐、汽水音乐、5sing、Bilibili、Apple Music。

专辑链接解析

支持直接解析专辑分享链接：

./music-dl -k "[https://music.163.com/#/album?id=123456](https://music.163.com/#/album?id=123456)"

支持解析的平台：网易云、QQ音乐、酷狗、酷我、咪咕、Jamendo、JOOX、千千音乐、汽水音乐、Apple Music。

常见问题

桌面应用相关

Q: 桌面应用打不开或显示空白？ 检查是否已安装 WebView2 运行时。从 Microsoft官网 下载安装最新版本。

Q: 桌面应用启动慢或卡顿？ 首次运行需要下载 WebView2 运行时。也可提前安装 Evergreen Bootstrapper 版本。

Q: 桌面应用启动时提示"另一个程序正在使用此文件"？ 这是因为上一次运行的后台进程没有正常退出。解决方案：

# 强制结束残留进程
taskkill /F /IM music-dl.exe

Q: 如何构建桌面应用？

构建 Rust 桌面应用

# 1. 构建 Go 二进制
go build -o desktop/music-dl.exe cmd/music-dl/main.go

# 2. 构建 Rust 桌面应用
cd desktop
cargo build --release

构建纯 Go 的桌面应用

cd desktop

# Windows 
go build -ldflags="-H windowsgui"

# Linux 
go build

Q: 桌面应用支持哪些平台？ 目前支持 Windows (x64/x86/arm64)、macOS (x64/arm64)、Linux (x64)。

通用问题

Q: 有些歌搜不到或下载失败？ 可能是付费限制、平台接口变更或网络问题。

Q: Web 模式打不开？ 检查端口是否占用，或浏览器插件是否拦截。

Q: 如何设置 Cookie 获取更高音质？ Web 右上角“设置”里可添加平台 Cookie。网易云音乐、QQ 音乐、酷狗音乐、Bilibili 支持点击输入框右侧的“扫码”按钮登录，扫码成功后会自动保存 Cookie。汽水音乐新版扫码登录暂未调通，入口已临时隐藏，请先手动配置 Cookie。

Q: 如何查看歌单分类和我的歌单？ Web 首页歌单入口旁提供“歌单分类”和“我的歌单”。歌单分类可直接浏览支持平台的官方分类；我的歌单需要先配置对应平台 Cookie，目前支持网易云音乐、QQ 音乐、酷狗音乐和汽水音乐。

Q: 开启“内嵌元数据”后没生效？ 先确认系统已安装 FFmpeg 且 ffmpeg -version 可执行；若不可用，程序会降级为原始音频下载（不内嵌封面/歌词）。

项目结构

go-music-dl/
├── cmd/
│   └── music-dl/          # CLI/TUI 主程序
├── core/                  # 核心业务逻辑
├── internal/
│   ├── cli/               # TUI 界面 (如: ui.go)
│   └── web/               # 重构后的 Web 后端服务
│       ├── templates/     # 前端模板与静态资源分离
│       ├── server.go      # Web 服务主入口
│       ├── music.go       # 音乐搜索与解析路由
│       ├── collection.go  # 本地自制歌单接口 (GORM)
│       ├── local_music.go # 本地音乐扫描、上传、封面/歌词与删除接口
│       └── videogen.go    # 视频生成后端支持
├── desktop/               # 桌面应用 (Rust + Tao/Wry)
├── desktop_go/            # 桌面应用 (Go + webview2 )
├── desktop_app/           # 移动应用 (Go + Gio )
├── data/                  # 🌟 统一数据持久化目录 (Docker挂载点)
│   ├── downloads/         # 下载的音乐文件
│   ├── video_output/      # 生成的视频文件
│   ├── cookies.json       # Cookie 配置文件
│   └── settings.db        # 统一 SQLite 数据库（设置 / Cookie / 自制歌单）
├── .github/workflows/     # GitHub Actions 工作流
├── .github/scripts/       # GitHub Actions 辅助脚本（Android FFmpeg 下载、注入与校验）
├── screenshots/           # 截图资源
├── docker-compose.yml     # Docker 生产环境配置 (直接拉取镜像)
├── docker-compose.dev.yml # Docker 开发环境配置 (本地构建)
├── Dockerfile             # Docker 构建配置
├── go.mod                 # Go 模块配置
├── README.md              # 主项目说明
├── package.bat            # 构建Rust桌面程序脚本
├── package_go.bat         # 构建Go桌面程序脚本
├── package_app.bat        # 构建Android移动应用脚本
├── package_ios.bat        # 构建IOS移动应用脚本
├── run.bat                # Go Music DL - 启动脚本 (Windows)
└── run.sh                 # Go Music DL - 启动脚本 (Linux/macOS)

技术栈

桌面应用架构

桌面应用采用前后端分离架构：

详细说明请参考 desktop/README.md

贡献

欢迎提交 Issue 或 Pull Request。

许可证

本项目遵循 GNU Affero General Public License v3.0（AGPL-3.0）。详情见 LICENSE。

致敬

感谢以下优秀的开源项目：

免责声明

仅供学习和技术交流使用。下载的音乐资源请在 24 小时内删除。

Star History

Star History Chart

go-music-dl (guohuiyuan/go-music-dl)

Searching Database…

5.4K ·GitHub
Go-music-dl
Что это такое?Go Music DL — это инструмент для поиска и скачивания музыки, написанный на Go. Он объединяет более 10 китайских стриминговых сервисов (NetEase Cloud, QQ Music, Kugou, Bilibili, Soda Music и другие) в одном приложении и позволяет скачивать музыку в формате FLAC без потерь, просматривать плейлисты и альбомы и управлять локальной библиотекой.
Это консольная утилита, веб-приложение или настольная программа?Сразу всё вместе: одна и та же серверная часть работает в веб-интерфейсе, в терминальном режиме TUI и в нативных приложениях для компьютера и телефона.
Как это запустить?Проще всего скачать готовый настольный файл (music-dl-desktop-go.exe или music-dl-desktop-rust.exe) из GitHub Releases и запустить его двойным кликом. Также доступны APK для Android, неподписанный IPA для iOS и отдельный веб-сервер с поддержкой обратного прокси Nginx.
Нужно ли мне устанавливать FFmpeg?Необязательно: FFmpeg/ffprobe нужны для встраивания обложек и текстов песен в файлы не в формате MP3 и для определения метаданных локальных аудиофайлов. Без них приложение работает, но пропускает эти дополнительные функции. Образы Docker и APK для Android уже включают ffmpeg/ffprobe.
Вход по QR-коду с Cookie работает на всех платформах?Вход по QR-коду сейчас работает для NetEase, QQ Music, Kugou и Bilibili. Вход сканированием QR-кода в Soda Music пока не работает из-за его динамических подписей системы контроля рисков, поэтому этот пункт скрыт, а Cookie нужно вводить вручную.
Можно запустить это на телефоне, а не только на компьютере?Да. Помимо исполняемых файлов для Windows/macOS/Linux и Docker, в релизах есть APK для Android (arm64-v8a, x86_64 или универсальный apk) и неподписанный IPA для iOS, который можно подписать самостоятельно.
Поддерживает ли это скачивание аудио без потерь?Да, источники NetEase Cloud, QQ Music и Bilibili поддерживают прямое скачивание аудио без потерь в формате FLAC.
Может ли оно управлять моей уже имеющейся локальной музыкальной библиотекой?Да, оно сканирует указанную папку для загрузок, читает встроенные обложки и тексты песен, определяет недостающие метаданные через ffprobe и может даже добавить ваши локальные треки как источник для поиска наряду с результатами из интернета.
Можно ли синхронизировать скачанные треки с WebDAV?Да, если в настройках включить синхронизацию с WebDAV, каждый скачанный файл будет автоматически загружаться на указанный адрес и в указанный путь WebDAV-сервера.
Нужно ли мне входить в аккаунт, чтобы пользоваться веб-интерфейсом?Нет. Поиск, воспроизведение, скачивание и просмотр плейлистов работают без аккаунта. Вход администратора нужен только для изменения системных настроек, управления Cookie платформ или использования входа по QR-коду.
What are similar projects?folia-major, openspot-music-app, SpotiFLAC, cliamp, SpotiFLAC-Next, TikTokDownloader, SpotiFLAC-Mobile, spotify-downloader
Which topics is it in?flac, qr-code, downloader, music, ffmpeg, tui, audio, agpl, sqlite, ios, web-app, go
Creator
guohuiyuan
Size
14 MB
Stars
5.4K
Updated
CommitOct 13Releasev1.1.2Oct 13
Age
8mo
Commits · 90 Days