开发文档

本指南面向开发者，介绍项目的技术架构和开发流程。

技术栈

• Electron - 跨平台桌面应用框架
• Vue 3 - 前端框架，使用 Composition API
• Vite - 构建工具
• Pinia - 状态管理
• Tailwind CSS - CSS 框架
• better-sqlite3 - 本地数据库

目录结构

gz-music-player/
├── electron/           # Electron 主进程
│   ├── main.js
│   ├── preload.js
│   ├── database.js
│   └── plugins/
├── src/                # 渲染进程 (Vue)
│   ├── components/
│   ├── views/
│   ├── stores/
│   ├── services/
│   ├── utils/
│   └── ui/
├── docs/               # VitePress 文档
└── build/              # 构建资源

开发环境

前置要求

• Node.js 18+
• npm 9+
• Git

安装与启动

# 克隆仓库
git clone https://github.com/your-username/gz-music-player.git
cd gz-music-player

# 安装依赖
npm install

# 启动开发模式
npm run dev

常用命令

命令	说明
npm run dev	启动 Vite + Electron 开发环境
npm run build	完整构建
npm run dist:win	打包 Windows 安装程序
npm run dist:mac	打包 macOS DMG
npm run dist:linux	打包 Linux AppImage

核心模块

主进程 (electron/main.js)

负责窗口管理、IPC 通信、系统集成、文件系统和数据库操作。

预加载脚本 (electron/preload.js)

通过 contextBridge 暴露安全的 API 给渲染进程。

数据库 (electron/database.js)

使用 better-sqlite3 管理本地数据，包括歌曲、播放列表等。

音乐服务 (src/services/music.js)

处理音乐平台 API 调用，包括搜索、获取播放链接、歌词等。

状态管理 (src/stores/)

使用 Pinia 管理应用状态：

• player.js - 播放器状态
• settings.js - 应用设置
• localMusic.js - 本地音乐
• ui.js - UI 状态

插件系统

插件结构

my-plugin/
├── index.js          # 插件入口
└── manifest.json     # 插件清单

插件清单示例

{
  "id": "my-plugin",
  "name": "我的插件",
  "version": "1.0.0",
  "description": "插件描述",
  "author": "作者",
  "platforms": ["netease", "qq"],
  "capabilities": ["search", "playUrl", "lyric"]
}

插件加密

# 加密
node electron/plugins/encrypt-tool.js encrypt my-plugin.js my-plugin.enc

# 解密
node electron/plugins/encrypt-tool.js decrypt my-plugin.enc my-plugin.js

IPC 通信

通道命名使用 kebab-case：

• netease-search
• qq-play-url
• kugou-lyric

推荐返回统一格式：

// 成功
{ success: true, data: results }

// 失败
{ success: false, error: error.message }

贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

提交规范

• feat: 添加新功能
• fix: 修复 bug
• docs: 更新文档
• style: 代码格式调整
• refactor: 重构代码
• test: 添加测试
• chore: 构建/工具变动