From fad454d98eb2c20e4352fd159e1cfb03456a47ab Mon Sep 17 00:00:00 2001
From: Yuhang Wu <YuhangWu@orbitmes.com>
Date: Wed, 12 Aug 2026 14:32:56 +0800
Subject: [PATCH] =?UTF-8?q?docs(README):=20=E6=9B=B4=E6=96=B0=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=E4=B8=BAYwYMusic=E9=A1=B9=E7=9B=AE=E4=BB=8B=E7=BB=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

更新README.md文件，将原有Tauri + Vue + TypeScript模板文档替换为YwYMusic
在线音乐播放器的详细介绍，包括功能特性、技术栈、项目结构、快速开始指南、
后端接口概览以及相关说明。
---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 117 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 12920b6..a07bcb5 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,120 @@
-# Tauri + Vue + TypeScript
+# YwYMusic 🎵
 
-This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.
+一款基于 **Tauri 2 + Vue 3** 的轻量在线音乐播放器。前端负责界面与播放，音乐数据、音频直链解析、扫码登录等能力由独立的音乐聚合后端提供。
 
-## Recommended IDE Setup
+## ✨ 功能特性
 
-- [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+### 音乐浏览
+- **发现音乐**：分类歌单（真实接口）、推荐歌单、新歌速递、排行榜精选
+- **排行榜**：多榜单预览，一键播放 / 进入歌单详情
+- **我的音乐**：我喜欢、最近播放、本地下载（当前为本地数据）
+- **搜索**：多源聚合搜索（单曲 / 歌单），输入防抖 + 竞态保护，热门词一键搜索
+- **歌单详情**：真实歌单数据、封面与播放量展示
+
+### 在线播放
+- 通过 `/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`（本地生成登录二维码） |
+| 状态管理 | 轻量 `reactive` store（无 Pinia 依赖） |
+| 工程化 | pnpm workspace、unplugin-auto-import、unplugin-vue-components |
+
+## 📁 项目结构
+
+```text
+YwYMusic
+├─ src/
+│  ├─ api/          # 后端接口封装（music / playlist / album / system）
+│  ├─ components/   # 通用组件（PlayerBar、SongTable、MusicCard、QrLogin 等）
+│  ├─ layouts/      # 主布局：侧边栏导航 + 内容区 + 底部播放条
+│  ├─ router/       # 路由定义
+│  ├─ stores/       # 轻量状态：player（播放器）、settings（音乐源设置）
+│  ├─ utils/        # 请求封装、封面防盗链代理、时间/数量格式化
+│  ├─ views/        # 页面：发现 / 排行榜 / 我的音乐 / 搜索 / 歌单详情 / 设置
+│  ├─ mocks/        # 本地兜底数据（排行榜、新歌、我的音乐）
+│  ├─ styles/       # 全局样式
+│  └─ types/        # 全局类型与自动生成声明
+├─ src-tauri/       # Tauri（Rust）壳与打包配置
+├─ 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"
+```
+
+请先启动后端服务，否则页面将回退到本地 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 读取 / 写入 |
+
+> 多源参数使用重复键形式传递，例如 `sources=kugou&sources=netease`。
+
+## 📝 说明与已知限制
+
+- **直链解析**：部分平台歌曲受版权 / VIP 限制，`/music/url` 可能无法返回可播放直链；建议先在「设置 → 扫码登录」完成对应平台登录。
+- **本地数据兜底**：排行榜、新歌速递、我的音乐目前使用本地 mock 数据；搜索、歌单详情、分类歌单已接入真实接口。
+- **专辑详情**：`/album/detail` 接口已封装，页面暂未接入。
+
+## 📄 许可证
+
+本项目仅用于学习与技术演示，请勿用于商业用途；音乐资源版权归各平台所有。