Go Music DL

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

🚀 快速开始

桌面应用 (推荐)

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

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

Web 模式

./music-dl web

TUI 模式

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

主要功能

多模式支持: Web 界面、TUI 终端、桌面应用
本地自制歌单: 支持新建本地收藏夹，随时收藏、管理心仪歌曲，数据持久化不丢失
无损音乐支持: 支持网易云、QQ 音乐、Bilibili 的 FLAC 无损音乐下载
多平台聚合搜索，支持单曲 / 歌单 / 专辑
试听、歌词、封面下载
Range 探测：显示大小与码率
汽水音乐等加密音频解密
过滤需要付费的资源
桌面应用特性: 原生窗口、自动服务启动、智能缓存管理

歌单 / 专辑支持

Web: 支持单曲、歌单、专辑三种搜索类型切换，可直接查看歌单 / 专辑曲目列表
链接解析: 支持直接粘贴歌单链接或专辑链接，自动识别来源并进入详情
TUI: 输入界面支持在单曲 / 歌单 / 专辑之间切换，适合整单 / 整专处理
详情跳转: Web 歌曲列表支持从歌曲跳转到歌手搜索结果或对应专辑页

Web 下载模式与 FFmpeg

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

默认关闭（推荐）：走流式下载，速度更快，并支持 Range 断点/拖动播放。
开启后：下载时会尝试把封面、歌词写入音频文件（embed）。

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

可先验证 FFmpeg 是否可用：

ffmpeg -version

常见安装方式：

Windows: winget install Gyan.FFmpeg
macOS: brew install ffmpeg
Ubuntu/Debian: sudo apt install ffmpeg

新增改动（简要）

Web 架构全面重构：前端代码彻底模块化（拆分独立的 JS / CSS / HTML 模板），后端路由按业务域拆分（音乐查询、歌单管理、视频生成），大幅提升代码可维护性。
新增自制歌单功能：Web 端支持本地收藏夹，用户可自由创建、编辑歌单，将不同平台的歌曲聚合收藏。
Web 试听按钮支持播放/停止切换，底部增加全局播放与音量控制栏。
Web 单曲支持“换源”，按相似度优先、时长接近、可播放验证。
换源自动排除 soda 与 fivesing。
TUI 增加 r 键批量换源，并显示换源进度。
增加“每日歌单推荐”，Web 和 TUI 都能看。
Web 端支持批量操作：全选、选择无效、批量下载、批量换源。

快速开始

桌面应用模式

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

特性

🖥️ 原生桌面窗口，无需浏览器
🚀 自动启动内置Web服务器
🎵 完整Web界面功能
📦 单文件分发，绿色免安装
🖼️ 自定义窗口图标
🔒 使用罕见端口(37777)，避免端口冲突

Docker 部署

本项目提供了多种 Docker 部署方式。当前默认通过 ./data 目录挂载到容器内 /home/appuser/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。

说明：

自动拉取 guohuiyuan/go-music-dl:latest 镜像
支持后台运行和自动重启
默认使用 ./data 本地目录做数据持久化，便于直接查看和备份
设置时区为亚洲上海
以非root用户(uid=1000)运行，提高安全性

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 --vg-cover --vg-audio --vg-lyric --vg-export

# 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 --vg-cover --vg-audio --vg-lyric --vg-export

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

CLI/TUI 模式

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

TUI 常用按键：

↑/↓ 移动
空格 选择
a 全选/清空
r 对勾选项换源
Enter 下载
b 返回
w 每日推荐歌单
q 退出

更多用法：

# 查看帮助
./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。

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

在你的仓库 Settings -> Secrets and variables -> Actions 中添加：

DOCKERHUB_USERNAME: 你的 DockerHub 用户名
DOCKERHUB_TOKEN: 你的 DockerHub 访问令牌

将 docker-compose.yml 中的镜像地址修改为你自己的：image: 你的用户名/go-music-dl:latest

Web 换源说明

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

先看歌名/歌手相似度
再看时长差异（太大就跳过）
最后做可播放探测

当前会跳过 soda 与 fivesing。

每日歌单推荐

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

支持平台

平台	包名	搜索	下载	歌词	歌曲解析	歌单搜索	歌单推荐	歌单歌曲	歌单链接解析	专辑搜索	专辑歌曲	专辑链接解析	备注
网易云音乐	`netease`	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	支持 FLAC 无损
QQ 音乐	`qq`	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	支持 FLAC 无损
酷狗音乐	`kugou`	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	支持普通歌曲 FLAC 无损
酷我音乐	`kuwo`	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
咪咕音乐	`migu`	✅	✅	✅	✅	❌	❌	❌	❌	✅	✅	✅
千千音乐	`qianqian`	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	✅
汽水音乐	`soda`	✅	✅	✅	✅	✅	❌	✅	✅	✅	✅	✅	音频解密
5sing	`fivesing`	✅	✅	✅	✅	✅	❌	✅	✅	❌	❌	❌
Jamendo	`jamendo`	✅	✅	✅	✅	❌	❌	❌	❌	✅	✅	✅
JOOX	`joox`	✅	✅	✅	❌	❌	❌	❌	❌	✅	✅	✅
Bilibili	`bilibili`	✅	✅	✅	✅	✅	❌	✅	✅	❌	❌	❌	支持 FLAC 无损

歌曲链接解析

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

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

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

歌单链接解析

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

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

支持解析的平台：网易云、QQ音乐、酷狗、酷我、汽水音乐、5sing、Bilibili。

专辑链接解析

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

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

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

常见问题

桌面应用相关

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

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

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

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

Q: 如何构建桌面应用？

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

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

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

通用问题

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

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

Q: 如何设置 Cookie 获取更高音质？ Web 右上角“设置”里可添加平台 Cookie。

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)
│       └── videogen.go    # 视频生成后端支持
├── desktop/               # 桌面应用 (Rust + Tao/Wry)
├── data/                  # 🌟 统一数据持久化目录 (Docker挂载点)
│   ├── downloads/         # 下载的音乐文件
│   ├── video_output/      # 生成的视频文件
│   ├── cookies.json       # Cookie 配置文件
│   └── settings.db        # 统一 SQLite 数据库（设置 / Cookie / 自制歌单）
├── .github/workflows/     # GitHub Actions 工作流
├── screenshots/           # 截图资源
├── docker-compose.yml     # Docker 生产环境配置 (直接拉取镜像)
├── docker-compose.dev.yml # Docker 开发环境配置 (本地构建)
├── Dockerfile             # Docker 构建配置
├── go.mod                 # Go 模块配置
└── README.md              # 主项目说明

技术栈

核心库: music-lib - 音乐平台搜索下载
CLI 框架: Cobra - 命令行工具
Web 框架: Gin - Web 框架
TUI 框架: Bubble Tea - 终端界面
桌面框架: Tao + Wry - 跨平台桌面应用
图像处理: image - 图标处理

桌面应用架构

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

前端: Rust + Tao/Wry - 负责窗口管理、WebView 渲染和进程管理
后端: Go 二进制 - 嵌入到桌面应用中，提供 Web 服务和音乐功能
通信: HTTP 本地服务 - 前后端通过 http://localhost:37777 通信

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

贡献

欢迎提交 Issue 或 Pull Request。

许可证

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

致敬

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

下载库: 0xHJK/music-dl - 音乐下载库
下载库: CharlesPikachu/musicdl - 音乐下载库
接口设计参考: metowolf/Meting - 多平台音乐聚合与接口封装
无损音乐: Suxiaoqinx/Netease_url - 网易云音乐 FLAC 无损音乐解析
QQ 音乐: Suxiaoqinx/qqmusic_flac - QQ 音乐 FLAC 解析

免责声明

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

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd/music-dl		cmd/music-dl
core		core
desktop		desktop
internal		internal
screenshots		screenshots
winres		winres
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
package.bat		package.bat
run.bat		run.bat
run.sh		run.sh

Latest commit

History

Folders and files

Repository files navigation