📌 项目简介

go-music-dl 是一个基于 Go 语言的全网音乐搜索与下载工具。它聚合了网易云、QQ音乐、酷狗、Bilibili、汽水音乐等 10+ 个主流平台，支持无损音质下载，并提供 Web 界面、TUI 终端、桌面应用和移动端 (Android) 四种使用模式。

🚀 方式一：桌面应用 (最简单推荐)

这是最开箱即用的方式，适合普通用户，无需安装任何环境。

第 1 步：下载应用

  1. 访问项目的 Releases 页面。
  2. 下载 music-dl-desktop-rust.exe (推荐) 或 music-dl-desktop-go.exe (备选)。

第 2 步：运行
解压下载的文件，双击 music-dl-desktop-rust.exe 即可运行。它会自动启动一个内置的 Web 服务器并打开原生应用窗口。

  • 特点：原生窗口体验，无需浏览器，自动处理端口，单文件绿色免安装。
  • 注意：若窗口空白，请检查并安装 WebView2 运行时 (微软官方下载)。

🐳 方式二：Docker 部署 (推荐服务器/远程访问)

适合在服务器上部署 Web 服务，实现远程访问。项目提供了两种 Docker Compose 配置。

1. 生产环境部署 (直接拉取镜像)

这是最推荐的 Docker 方式，无需本地构建，直接使用预编译镜像。

第 1 步：准备数据目录
在项目目录下创建数据文件夹（用于持久化配置和下载的音乐）：

1
mkdir -p data && chmod 777 data

第 2 步：启动服务
使用项目根目录下的 docker-compose.yml：

1
2
3
4
5
6
# 拉取最新镜像并后台启动
docker compose pull
docker compose up -d --remove-orphans

# 或者一条命令完成拉取和启动
docker compose up -d --pull always --remove-orphans

第 3 步：访问服务
浏览器打开 http://你的服务器IP:8080 即可使用。

第 4 步：常用管理命令

1
2
3
4
5
# 查看日志
docker compose logs -f

# 停止服务
docker compose down

2. 开发环境部署 (本地构建镜像)

如果你修改了源码，希望本地构建镜像测试，使用此方式：

1
docker compose -f docker-compose.dev.yml up -d --build --remove-orphans

3. 纯命令行部署 (docker run)

如果不使用 Compose，也可直接运行：

1
2
3
4
5
6
7
8
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 用户：将 $(pwd) 替换为 ${PWD}。

🌐 方式三：Web 服务模式 (直接运行)

如果你有 Go 环境，或下载了预编译的 CLI 可执行文件，可以直接运行 Web 服务。

第 1 步：获取程序

  • 从 Release 下载：下载对应系统的 music-dl 可执行文件。

  • 或从源码编译 (需 Go 1.25+)：

    1
    2
    3
    git clone https://github.com/guohuiyuan/go-music-dl.git
    cd go-music-dl
    go build -o music-dl cmd/music-dl/main.go

第 2 步：启动 Web 服务

1
2
3
4
5
# 默认启动，监听 8080 端口，挂载路径为 /music
./music-dl web

# 指定端口和挂载路径
./music-dl web --port 9090 --base-path /dl

启动后访问 http://127.0.0.1:8080 (或你指定的端口)。

Web 模式关键说明：

  • 普通功能 (搜索、播放、下载、浏览歌单) 无需登录。
  • 管理员登录：修改系统设置、管理 Cookie 等需要登录。首次触发设置时，终端会打印一个一次性初始化令牌，打开初始化页面填入令牌并设置用户名/密码 (≥6位) 即可创建管理员账号。
  • 反向代理：若挂载到二级目录 (如 /dl/)，启动时需加 --base-path /dl，并参考项目文档配置 Nginx。

💻 方式四：CLI / TUI 模式 (终端使用)

适合在终端环境快速搜索和下载。

基本用法：

1
2
3
4
5
6
7
8
9
10
11
# 搜索并下载
./music-dl -k "周杰伦"

# 指定搜索源 (网易云、QQ)
./music-dl -k "晴天" -s netease,qq

# 指定下载目录并下载封面和歌词
./music-dl -k "周杰伦" -o ./my_music --cover --lyrics

# 解析歌单或专辑链接
./music-dl -k "https://music.163.com/#/playlist?id=123456"

TUI (终端交互界面) 常用按键：

  • ↑/↓ 选择
  • 空格 选择/取消歌曲
  • a 全选/清空
  • r 对选中的歌曲进行换源
  • Enter 下载选中的歌曲
  • w 查看每日推荐歌单
  • q 退出

📱 移动端 (Android APK)

项目为 Android 提供了 APK 安装包，可在 Releases 页面下载：

  • 推荐：music-dl_arm64-v8a.apk (适用于绝大多数现代 Android 设备)。
  • 备选：music-dl.apk (无分片兼容包，仅当上述版本无法安装时使用)。

安装后，建议在 Web 界面右上角 设置 中，将“本地下载目录”改为 /sdcard/Music，方便系统音乐应用识别。

⚙️ 重要配置与功能说明

  • FFmpeg 依赖：Web 设置中的“下载时内嵌元数据 (封面/歌词)”功能依赖 FFmpeg。未安装时此功能无效，但不影响核心下载。安装方法：Windows (winget install Gyan.FFmpeg)，macOS (brew install ffmpeg)，Ubuntu (sudo apt install ffmpeg)。Docker 和 Android APK 已内置。
  • Cookie 与扫码登录：在 Web 设置中可为各平台配置 Cookie，以获取更高音质或读取“我的歌单”。网易云、QQ、酷狗、Bilibili 支持点击“扫码”按钮，用官方 App 扫码自动登录。汽水音乐的扫码登录暂未调通，需手动配置 Cookie。
  • 本地音乐管理：Web 端提供“本地音乐”入口，可扫描、上传、管理下载目录中的音频，支持分页、缓存、添加到自制歌单。
  • 数据持久化：所有配置、Cookie、下载的音乐、自制歌单均保存在项目目录下的 data/ 文件夹中 (Docker 部署已挂载此目录)，方便备份和迁移。

💎 总结

go-music-dl 部署方式非常灵活：

  • 个人桌面使用，首选桌面应用，下载即用。
  • 服务器远程访问或团队共享，推荐 Docker 部署 (docker compose up -d)。
  • 开发者或终端爱好者，可使用 Web 服务 或 CLI/TUI 模式。

无论哪种方式，核心数据都保存在 data/ 目录，便于管理。配置好 Cookie 后，即可享受聚合搜索、无损下载和歌单管理的完整体验。