mirror of
https://github.com/algerkong/AlgerMusicPlayer.git
synced 2026-04-03 14:20:50 +08:00
199 lines
6.4 KiB
Markdown
199 lines
6.4 KiB
Markdown
# Alger Music Player 开发文档
|
||
|
||
## 项目结构
|
||
|
||
### 技术栈
|
||
|
||
- **前端框架**：Vue 3 + TypeScript
|
||
- **UI 组件库**：naive-ui
|
||
- **样式框架**：Tailwind CSS
|
||
- **图标库**：remixicon
|
||
- **状态管理**：Pinia
|
||
- **工具库**：VueUse
|
||
- **构建工具**：Vite, electron-vite
|
||
- **打包工具**：electron-builder
|
||
- **国际化**：vue-i18n
|
||
- **HTTP 客户端**：axios
|
||
- **本地存储**：electron-store localstorage
|
||
- **音乐 API**：netease-cloud-music-api
|
||
- **音乐解锁**：@unblockneteasemusic/server
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
AlgerMusicPlayer/
|
||
├── build/ # 构建相关文件
|
||
├── docs/ # 项目文档
|
||
├── node_modules/ # 依赖包
|
||
├── out/ # 构建输出目录
|
||
├── resources/ # 资源文件
|
||
├── src/ # 源代码
|
||
│ ├── i18n/ # 国际化配置
|
||
│ │ ├── lang/ # 语言包
|
||
│ │ ├── main.ts # 主进程国际化入口
|
||
│ │ └── renderer.ts # 渲染进程国际化入口
|
||
│ ├── main/ # Electron 主进程
|
||
│ │ ├── modules/ # 主进程模块
|
||
│ │ ├── index.ts # 主进程入口
|
||
│ │ ├── lyric.ts # 歌词处理
|
||
│ │ ├── server.ts # 服务器
|
||
│ │ ├── set.json # 设置
|
||
│ │ └── unblockMusic.ts # 音乐解锁
|
||
│ ├── preload/ # 预加载脚本
|
||
│ │ ├── index.ts # 预加载脚本入口
|
||
│ │ └── index.d.ts # 预加载脚本类型声明
|
||
│ └── renderer/ # Vue 渲染进程
|
||
│ ├── api/ # API 请求
|
||
│ ├── assets/ # 静态资源
|
||
│ ├── components/ # 组件
|
||
│ │ ├── common/ # 通用组件
|
||
│ │ ├── home/ # 首页组件
|
||
│ │ ├── lyric/ # 歌词组件
|
||
│ │ ├── settings/ # 设置组件
|
||
│ │ └── ... # 其他组件
|
||
│ ├── const/ # 常量定义
|
||
│ ├── directive/ # 自定义指令
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ ├── layout/ # 布局组件
|
||
│ ├── router/ # 路由配置
|
||
│ ├── services/ # 服务
|
||
│ ├── store/ # Pinia 状态管理
|
||
│ │ ├── modules/ # Pinia 模块
|
||
│ │ └── index.ts # Pinia 入口
|
||
│ ├── type/ # 类型定义
|
||
│ ├── types/ # 更多类型定义
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── views/ # 页面视图
|
||
│ ├── App.vue # 根组件
|
||
│ ├── index.css # 全局样式
|
||
│ ├── index.html # HTML 模板
|
||
│ ├── main.ts # 渲染进程入口
|
||
│ └── ... # 其他文件
|
||
├── .env.development # 开发环境变量
|
||
├── .env.development.local # 本地开发环境变量
|
||
├── .env.production.local # 本地生产环境变量
|
||
├── .eslintrc.cjs # ESLint 配置
|
||
├── .gitignore # Git 忽略文件
|
||
├── .prettierrc.yaml # Prettier 配置
|
||
├── electron-builder.yml # electron-builder 配置
|
||
├── electron.vite.config.ts # electron-vite 配置
|
||
├── package.json # 项目配置
|
||
├── postcss.config.js # PostCSS 配置
|
||
├── tailwind.config.js # Tailwind 配置
|
||
├── tsconfig.json # TypeScript 配置
|
||
├── tsconfig.node.json # 节点 TypeScript 配置
|
||
└── tsconfig.web.json # Web TypeScript 配置
|
||
```
|
||
|
||
### 主要组件说明
|
||
|
||
#### 主进程 (src/main)
|
||
|
||
主进程负责创建窗口、处理系统层面的交互以及与渲染进程的通信。
|
||
|
||
- **index.ts**: 应用主入口，负责创建窗口和应用生命周期管理
|
||
- **lyric.ts**: 歌词解析和处理
|
||
- **unblockMusic.ts**: 音乐解锁功能
|
||
- **server.ts**: 本地服务器
|
||
|
||
#### 预加载脚本 (src/preload)
|
||
|
||
预加载脚本在渲染进程加载前执行，提供了渲染进程和主进程之间的桥接功能。
|
||
|
||
#### 渲染进程 (src/renderer)
|
||
|
||
渲染进程是基于 Vue 3 的前端应用，负责 UI 渲染和用户交互。
|
||
|
||
- **components/**: 包含各种 UI 组件
|
||
- **common/**: 通用组件
|
||
- **home/**: 首页相关组件
|
||
- **lyric/**: 歌词显示组件
|
||
- **settings/**: 设置界面组件
|
||
- **MusicList.vue**: 音乐列表组件
|
||
- **MvPlayer.vue**: MV 播放器
|
||
- **EQControl.vue**: 均衡器控制
|
||
- **...**: 其他组件
|
||
|
||
- **store/**: Pinia 状态管理
|
||
- **modules/**: 各功能模块的状态管理
|
||
- **index.ts**: 状态管理入口
|
||
|
||
- **views/**: 页面视图组件
|
||
|
||
- **router/**: 路由配置
|
||
|
||
- **api/**: API 请求封装
|
||
|
||
- **utils/**: 工具函数
|
||
|
||
### 开发指南
|
||
|
||
#### 命名约定
|
||
|
||
- 目录使用 kebab-case (如: components/auth-wizard)
|
||
- 组件文件名使用 PascalCase (如: AuthWizard.vue)
|
||
- 可组合式函数使用 camelCase (如: useAuthState.ts)
|
||
|
||
#### 代码风格
|
||
|
||
- 使用 Composition API 和 `<script setup>` 语法
|
||
- 使用 TypeScript 类型系统
|
||
- 优先使用类型而非接口
|
||
- 避免使用枚举，使用 const 对象代替
|
||
- 使用 tailwind 实现响应式设计
|
||
|
||
### 如何启动？
|
||
|
||
安装依赖（最好使用node18+）：
|
||
|
||
```
|
||
npm install
|
||
```
|
||
|
||
#### 桌面端开发
|
||
|
||
启动桌面端开发：
|
||
|
||
```
|
||
npm run dev
|
||
```
|
||
|
||
#### 网页端开发
|
||
|
||
如果只启动网页端开发，需要自己部署服务 netease-cloud-music-api
|
||
|
||
需要复制一份 `.env.development.local` 到 `src/renderer` 下
|
||
|
||
```
|
||
# .env.development.local
|
||
|
||
# 你的接口地址 (必填)
|
||
VITE_API = ***
|
||
# 音乐破解接口地址
|
||
VITE_API_MUSIC = ***
|
||
```
|
||
|
||
启动web端开发：
|
||
|
||
```
|
||
npm run dev:web
|
||
```
|
||
|
||
### 打包
|
||
|
||
打包桌面端：
|
||
|
||
```
|
||
npm run build:win
|
||
```
|
||
|
||
打包后的文件在 /dist 下
|
||
|
||
打包网页端：
|
||
|
||
```
|
||
npm run build
|
||
```
|
||
|
||
打包后的文件在 /out/renderer 下
|