AlgerMusicPlayer/DEV.md

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 下