外观
客户端使用教程
拼好歌是一款跨平台的个人音乐播放器工具，支持鸿蒙 / iPhone / Android / Windows / macOS / Linux。客户端基于 uni-app + Vue 3 开发，桌面端由 Electron 承载，一套代码同时构建移动端与桌面端。
界面简洁无广告，提供播放控制、歌单管理、数据同步、定时关闭、后台播放、暗黑模式等功能。
使用流程只有三步
获取客户端 → 选择服务器模式 → 导入自行准备的音源插件。
平台支持
| 平台 | 承载方式 | 说明 |
|---|---|---|
| Android | uni-app App 端 | 原生打包，提供安装包 |
| Windows / macOS / Linux | Electron | 桌面应用，提供安装包 |
| iOS | 小程序 | 无预编译安装包，需用微信开发者工具自行编译运行 |
| 华为纯血鸿蒙 | 小程序 | 同上；暂无原生安装包 |
各平台能力差异（尤其是插件能否在本机执行）见平台与运行模式。
获取客户端
Android / Windows / macOS / Linux
直接下载安装包即可，无需配置开发环境。各平台安装包见下载。
iOS / 华为纯血鸿蒙：用微信开发者工具编译小程序
这两个系统没有可直接安装的包，需要自己用微信开发者工具编译运行。完整流程分三步，与项目 README 一致。
第一步：准备环境
- 下载项目代码到电脑 —— 地址见代码仓库。
- 注册微信小程序开发者，拿到自己的 AppID —— 这个 AppID 不能分享给他人使用，每个使用者都要自己注册一个。注册方式见微信小程序快速开始。
- 安装微信开发者工具 —— 下载安装后，打开项目并在项目设置里填入上一步的 AppID。
第二步：配置项目
- 在开发者工具中配置「不校验合法域名」 —— 见配置说明。
- 生成预览二维码 —— 点开发者工具右上角的「预览」，生成二维码供手机扫描。
第三步：手机端配置
- 开启开发者模式 —— 手机扫码打开小程序，按开启开发者模式操作。
- 选择服务器模式 —— 首次使用会自动弹出模式选择，也可以在设置 → 服务器地址里随时切换。选「专属服务器」时点击「添加服务器地址」，填入
https://你的域名/你的API_KEY，点测试确认连通后保存。 - 导入音源插件 —— 在设置 → 音源插件管理里点「在线导入」，填入音源插件脚本地址，点「导入」，然后在列表里把它设为默认调用的音源插件。
小程序里插件只能在服务端跑
iOS 与鸿蒙走小程序运行时，没有可用的 WebAssembly 执行环境，网络请求又受域名白名单限制，因此插件必须在专属服务器上执行。这也是为什么这两个平台必须先准备好一台自己的服务端 —— 详见平台与运行模式。
选择服务器模式
首次打开客户端会弹出服务器模式选择。
专属服务器：填入你自己的服务器地址（格式 https://你的域名/你的API_KEY），点测试连通后保存。支持多端同步、AI 推荐等完整功能。
服务器怎么来：可以按服务端部署使用教程自己部署一套，也可以使用项目配套的服务端仓库。
版本兼容
客户端会自动检查服务端版本兼容性，版本过低时会弹窗提醒升级。最低要求服务端版本为 v1.0.10。
导入音源插件
- 打开设置 → 音源插件管理；
- 点在线导入，填入音源插件脚本地址（也支持从设备选择文件导入、粘贴原始内容导入）；
- 点导入，然后在列表里把它设为默认调用的音源插件。
建议导入 2–3 个音源插件：某个插件不可用时会自动切换到其他可用插件。
关于音源插件
- 本项目不提供任何音源插件，也不提供插件的修改与定制服务；
- 插件由使用者自行准备、自行评估，请自行确认其来源与授权合法合规，本项目不对第三方插件的内容与行为负责；
- 目前只支持洛雪音乐（lx-music）音源脚本生态，其他格式的插件不能直接使用；其中小部分脚本不兼容，混淆过的脚本暂不支持。
想自己写一个插件？见音源插件使用教程：支持范围、脚本结构、globalThis.lx API 与调试方法都在那一页。
功能模块
| 模块 | 主要功能 |
|---|---|
| 首页 | 轮播推荐、猜你喜欢、排行榜广场、歌单广场、推荐歌单、新歌速递；听歌识曲（麦克风录音与内部音频识别，保留最近 50 条记录） |
| 搜索 | 多音源插件聚合搜索，支持歌曲 / 歌单 / 歌手 / 专辑；搜索历史、热搜榜、搜索建议 |
| 播放器 | 全屏播放器、迷你播放器、播放模式切换、进度控制、歌词实时同步、收藏、音源提供者展示 |
| 播放列表 | 试听列表、我的收藏、播放历史、自定义歌单管理、歌单导入导出 |
| 排行榜 | 各平台热歌榜、新歌榜、飙升榜与分类排行 |
| 我的 | 歌曲统计（我的歌曲 / 累计听歌 / 今日时长 / 最爱歌手）、歌单管理、播放历史、收藏 |
| 歌单广场 | 精选推荐、分类浏览、歌单详情预览 |
| AI 推荐 | 智能推荐、音乐画像卡片、推荐偏好面板（场景 / 探索程度 / 年代 / 语言） |
| 账号与同步 | 邮箱注册登录、设备登录信息、云同步、同步频率调节、本地 JSON 备份与恢复 |
| 设置 | 服务器地址管理、播放音质、音源插件管理、主题与暗黑模式、账号管理、定时停止播放 |
数据与账号
- 未登录：歌单、收藏等数据保存在本地设备；
- 登录后：歌单、播放历史、设置同步到你自己部署的服务端，多设备保持一致；
- 本地备份：歌单或全部用户数据可导出为
.json文件，选择文件后自动识别恢复。
云同步需要连接专属服务器并登录账号；注册通常需要管理员发放的邀请码。
技术栈
| 项目 | 说明 |
|---|---|
| 框架 | uni-app + Vue 3 |
| 桌面端 | Electron |
| 状态管理 | 组合式 API（composables）+ 本地存储 |
| 构建 | HBuilderX 或 uni-launch 命令行 |
本地构建
bash
# 获取代码
git clone https://codeberg.org/erikjamesgz/phg-music.git
cd phg-music
# 安装依赖
npm install
# 构建产物（供 Electron 打包与本地调试）
npm run dev:web
# 各端调试
npm run dev:app-android
npm run dev:app-ios
npm run dev:app-harmony也可直接用 HBuilderX 打开项目，通过「运行」菜单选择目标平台。
桌面端（Electron）需先构建产物，再由 Electron 工程打包。
常见问题
导入插件后无法播放？
该插件在当前版本里不被支持，换一个插件试试。
播放异常或换源失败？
部分混淆过的插件不支持，建议使用未混淆的插件；也可以多导入几个插件，让客户端在失败时自动切换。
需要几个插件才够用？
建议 2–3 个。单个插件经常因为上游接口变动而失效，多准备几个能显著减少播放失败。
还有别的问题？
先翻更新日志确认当前版本有哪些能力、是不是已经修过。仍然解决不了的，可以加入反馈 QQ 群（群号 1016773775）直接问，或者在仓库 Issue 里留一条，附上平台、版本与复现步骤。