# music-square

**Repository Path**: cc-2018_admin/music-square

## Basic Information

- **Project Name**: music-square
- **Description**: 一个基于 uni-app + Vue 3 + TypeScript的移动端音乐搜索与播放项目，支持多音源搜索、歌曲详情播放、同步歌词、本地收藏和缓存清理，仅学习交流，请勿商用
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MusicSquare

一个基于 `uni-app + Vue 3 + TypeScript` 的移动端音乐搜索与播放项目，支持多音源搜索、歌曲详情播放、同步歌词、本地收藏和缓存清理。

## 功能概览

- 多音源搜索：支持 `QQ 音乐`、`咪咕`、`网易云`、`酷我`
- 结果排序：按关键词匹配度排序，最符合搜索词的歌曲优先展示
- 首页双 Tab：
  - `歌曲`：搜索结果 / 最近搜索列表
  - `我的`：本地收藏列表 + 清除缓存
- 详情播放页：
  - 播放 / 暂停 / 上一首 / 下一首
  - 进度拖动
  - 音量调节
  - 歌词高亮与自动跟随
  - 手动滚动歌词后，停止滚动 3 秒自动回到当前播放位置
- 本地收藏：
  - 可在歌曲列表中收藏 / 取消收藏
  - 收藏结果本地持久化
  - 在 `我的` 中点击收藏歌曲可直接进入详情页并开始播放
- 清除缓存：
  - 一键清空本地收藏、搜索历史、当前播放上下文和本地配置

## 页面结构

### 1. 首页 `pages/index/index`

- `歌曲` Tab：展示最近搜索 / 当前搜索结果
- `我的` Tab：展示本地收藏和清除缓存入口
- 底部固定区域：
  - 搜索框与搜索按钮
  - `歌曲 / 我的` 自定义 TabBar

### 2. 歌曲详情 `pages/detail/index`

- 展示歌曲封面、标题、来源、音质
- 提供播放控制与进度控制
- 提供歌词滚动与自动定位
- 上一首 / 下一首会跟随进入详情页时的来源列表：
  - 从搜索列表进入，就跟随搜索列表切歌
  - 从收藏列表进入，就跟随收藏列表切歌

## 技术栈

- `uni-app`
- `Vue 3`
- `TypeScript`
- `Vite`
- `Vitest`

## 本地缓存说明

当前项目会在本地持久化以下内容：

- 收藏歌曲列表
- 首页当前 Tab 状态

清除缓存后，会同时清空：

- 本地收藏
- 搜索历史
- 当前播放上下文
- 本地配置

## 开发命令

安装依赖：

```bash
npm install
```

启动 H5 开发：

```bash
npm run dev:h5
```

构建 H5：

```bash
npm run build:h5
```

运行测试：

```bash
npm test
```

项目也保留了 uni-app 的多端脚本，例如：

- `npm run dev:mp-weixin`
- `npm run build:mp-weixin`
- `npm run dev:mp-qq`
- `npm run build:mp-qq`

## 项目结构

```text
src/
├── components/music/      # 首页、详情页相关组件
├── composables/          # 搜索与播放逻辑
├── pages/
│   ├── index/            # 首页
│   └── detail/           # 歌曲详情页
├── services/             # 第三方音乐接口封装
├── store/                # 会话状态与收藏/队列状态
├── test/                 # Vitest 测试
├── types/                # TypeScript 类型
└── utils/                # 排序、布局、导航、缓存等工具函数
```

## 关键模块

- `src/composables/useMusicSearch.ts`
  - 搜索多音源歌曲
  - 按关键词匹配度排序
- `src/composables/useAudioPlayer.ts`
  - 管理播放状态、进度、歌词同步
- `src/store/music-session.ts`
  - 管理搜索历史、收藏、当前 Tab、播放队列
- `src/utils/home-storage.ts`
  - 管理收藏和首页状态的本地持久化
- `src/services/music-api.ts`
  - 聚合第三方搜索 / 播放 / 歌词接口

## 测试与质量

当前项目已覆盖的核心行为包括：

- 搜索结果排序
- 会话列表与收藏状态
- 本地缓存读写
- 播放异常兜底
- 歌词自动滚动计算
- 导航逻辑

## 注意事项

- 播放、搜索、歌词依赖第三方接口，接口可用性和返回格式变化会直接影响功能
- 某些音源在 H5 环境下可能受浏览器编解码能力或跨域策略影响
- 项目当前更偏向移动端布局，H5 主要作为移动视图使用

## 后续可扩展方向

- 收藏列表排序与编辑
- 最近播放记录
- 播放模式（顺序 / 单曲 / 随机）
- 更完整的多端适配
- 收藏与设置的云端同步