# 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", &params).await?;

// 显式请求 METING_API_URL
state.get_at(ApiEndpoint::Meting, "/api", &params).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` 接口已封装，页面暂未接入。

## 📄 许可证

本项目仅用于学习与技术演示，请勿用于商业用途；音乐资源版权归各平台所有。