146 lines
5.8 KiB
Markdown
146 lines
5.8 KiB
Markdown
# YwYMusic 🎵
|
||
|
||
一款基于 **Tauri 2 + Vue 3** 的轻量在线音乐播放器。前端负责界面与播放，音乐数据、音频直链解析、扫码登录等能力由独立的音乐聚合后端提供。
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 音乐浏览
|
||
- **发现音乐**：分类歌单（真实接口）、推荐歌单、新歌速递、排行榜精选
|
||
- **排行榜**：多榜单预览，一键播放 / 进入歌单详情
|
||
- **我的音乐**：我喜欢、最近播放、本地下载（当前为本地数据）
|
||
- **搜索**：多源聚合搜索（单曲 / 歌单），输入防抖 + 竞态保护，热门词一键搜索
|
||
- **歌单详情**：真实歌单数据、封面与播放量展示
|
||
|
||
### 在线播放
|
||
- 通过 `/music/url` 获取平台**音频直链**并真实播放（`<audio>`）
|
||
- 播放队列、上一首 / 下一首、随机播放、单曲循环
|
||
- 进度拖动、音量控制、静音
|
||
- 全屏播放器（封面旋转动效 + 歌词区域）
|
||
- 歌曲切换自动按平台解析直链，失败时优雅兜底
|
||
|
||
### 设置与账号
|
||
- **音乐源配置**：勾选参与搜索的平台（多选），并从全部平台中任选一个作为默认源
|
||
- **扫码登录**：支持网易云、QQ 音乐、酷狗、Bilibili 等平台，二维码本地生成，轮询登录状态，成功后自动写入平台 Cookies，提升直链解析成功率
|
||
|
||
## 🛠 技术栈
|
||
|
||
| 分类 | 技术 |
|
||
| --- | --- |
|
||
| 桌面框架 | [Tauri 2](https://tauri.app)（Rust + 系统 WebView） |
|
||
| 前端框架 | Vue 3（`<script setup>`）+ TypeScript |
|
||
| 构建工具 | Vite |
|
||
| UI 组件库 | [Naive UI](https://www.naiveui.com) |
|
||
| 路由 | Vue Router（Hash 模式，兼容 Tauri `file://` 协议） |
|
||
| 网络请求 | Axios（统一拦截器 + 业务码处理） |
|
||
| 二维码 | `qrcode`（本地生成登录二维码） |
|
||
| 状态管理 | Pinia + pinia-plugin-persistedstate（持久化设置与搜索历史） |
|
||
| 工程化 | pnpm workspace、unplugin-auto-import、unplugin-vue-components |
|
||
|
||
## 📁 项目结构
|
||
|
||
```text
|
||
YwYMusic
|
||
├─ src/
|
||
│ ├─ api/ # 后端接口封装（music / playlist / album / system）
|
||
│ ├─ components/ # 通用组件（PlayerBar、SongTable、MusicCard、QrLogin 等）
|
||
│ ├─ layouts/ # 主布局：侧边栏导航 + 内容区 + 底部播放条
|
||
│ ├─ router/ # 路由定义
|
||
│ ├─ stores/ # Pinia 状态：player（播放器）、settings（音乐源设置）、searchHistory（搜索历史）
|
||
│ ├─ utils/ # 请求封装、封面防盗链代理、时间/数量格式化
|
||
│ ├─ views/ # 页面：发现 / 排行榜 / 我的音乐 / 搜索 / 歌单详情 / 设置
|
||
│ ├─ mocks/ # 本地兜底数据（排行榜、新歌、我的音乐）
|
||
│ ├─ styles/ # 全局样式
|
||
│ └─ types/ # 全局类型与自动生成声明
|
||
├─ src-tauri/ # Tauri（Rust）壳与打包配置
|
||
│ ├─ src/
|
||
│ │ ├─ commands/ # Tauri 命令（music_url 等）
|
||
│ │ ├─ services/ # HTTP 客户端（支持 GO_MUSIC_URL / METING_API_URL 切换）
|
||
│ │ └─ models.rs # 数据模型与 API 地址常量
|
||
│ └─ Cargo.toml
|
||
├─ index.html
|
||
└─ package.json
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+ 与 [pnpm](https://pnpm.io)
|
||
- 桌面端开发需安装 [Rust 工具链](https://www.rust-lang.org/tools/install)
|
||
- 音乐聚合后端（见下文「后端接口」）
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 仅启动前端开发服务器（默认 http://localhost:1420）
|
||
pnpm dev
|
||
|
||
# 以桌面应用方式运行（推荐，Tauri 环境）
|
||
pnpm tauri dev
|
||
|
||
# 前端类型检查 + 生产构建
|
||
pnpm build
|
||
|
||
# 打包桌面安装包
|
||
pnpm tauri build
|
||
```
|
||
|
||
### 后端配置
|
||
|
||
前端通过环境变量 `VITE_BASE_API_URL` 访问音乐聚合后端，默认指向本地服务：
|
||
|
||
```env
|
||
VITE_BASE_API_URL = "http://127.0.0.1:8080"
|
||
```
|
||
|
||
Rust 后端同时配置了两个 API 地址常量（`src-tauri/src/models.rs`）：
|
||
|
||
```rust
|
||
pub const GO_MUSIC_URL: &str = "http://127.0.0.1:8080"; // 音乐聚合后端
|
||
pub const METING_API_URL: &str = "http://127.0.0.1:81"; // Meting API
|
||
```
|
||
|
||
`HttpClient` 支持通过 `ApiEndpoint` 枚举在请求时选择目标地址：
|
||
|
||
```rust
|
||
use crate::services::http::{ApiEndpoint, HttpClient};
|
||
|
||
// 默认请求 GO_MUSIC_URL
|
||
state.get("/api/v1/playlist/recommend", ¶ms).await?;
|
||
|
||
// 显式请求 METING_API_URL
|
||
state.get_at(ApiEndpoint::Meting, "/api", ¶ms).await?;
|
||
```
|
||
|
||
请先启动后端服务，否则页面将回退到本地 mock 数据或提示网络异常。
|
||
|
||
## 🔌 后端接口概览
|
||
|
||
| 模块 | 接口 | 说明 |
|
||
| --- | --- | --- |
|
||
| 音乐 | `/api/v1/music/search` | 多源聚合搜索（单曲 / 歌单 / 专辑） |
|
||
| 音乐 | `/api/v1/music/url` | 获取音频裸直链 |
|
||
| 音乐 | `/api/v1/music/stream` | 音频流代理（跨域防盗链） |
|
||
| 音乐 | `/api/v1/music/lyric` | 获取歌词 |
|
||
| 歌单 | `/api/v1/playlist/detail` | 歌单详情 |
|
||
| 歌单 | `/api/v1/playlist/categories` | 歌单分类 |
|
||
| 专辑 | `/api/v1/album/detail` | 专辑详情 |
|
||
| 系统 | `/api/v1/system/qr_login/*` | 扫码登录会话与状态轮询 |
|
||
| 系统 | `/api/v1/system/cookies` | 平台 Cookies 读取 / 写入 |
|
||
| Meting | `/api` | Meting API（通过 `music_url` 命令调用） |
|
||
|
||
> 多源参数使用重复键形式传递，例如 `sources=kugou&sources=netease`。
|
||
|
||
## 📝 说明与已知限制
|
||
|
||
- **直链解析**：部分平台歌曲受版权 / VIP 限制，`/music/url` 可能无法返回可播放直链；建议先在「设置 → 扫码登录」完成对应平台登录。
|
||
- **本地数据兜底**：排行榜、新歌速递、我的音乐目前使用本地 mock 数据；搜索、歌单详情、分类歌单已接入真实接口。
|
||
- **专辑详情**：`/album/detail` 接口已封装，页面暂未接入。
|
||
|
||
## 📄 许可证
|
||
|
||
本项目仅用于学习与技术演示，请勿用于商业用途；音乐资源版权归各平台所有。
|