LoveLiveMusicPlayer-Next/README.md

LoveLiveMusicPlayer · 桌面端

基于 electron-vite 的 LoveLive! 音乐播放器 PC 端，复刻原 Electron 项目功能。

设计目标之一：为后续移动端（Flutter）预留最大兼容性与可扩展性。 双端联动协议被抽取为独立、框架无关的共享模块 src/shared/protocol，移动端可直接对照复用。

技术栈

维度	选型
框架	Electron 43 + Vite 7 + React 19 + TypeScript
脚手架	electron-vite
状态管理	Zustand
样式	Tailwind CSS 3（src/renderer/src/styles/index.css）
本地数据库	better-sqlite3（表结构与移动端 SQLite 对齐）
配置存储	electron-store
局域网通信	ws（WebSocket 服务端）+ express（HTTP 文件服务），运行在主进程
二维码	qrcode.react
音频转码	ffmpeg-static（iOS flac→wav，跨平台免编译）
图标	lucide-react

目录结构

src/
├── shared/                     # ★ 双端共享（协议 + 领域模型 + IPC 通道常量）
│   ├── protocol/               #   命令枚举 / 类型 / 端口 / 版本协商（移动端可复用）
│   ├── models/                 #   Album/Music/Menu/Love/History/Lyric（对齐移动端实体）
│   └── ipc/channels.ts
├── main/                       # 主进程
│   ├── index.ts                #   入口（单例锁、生命周期）
│   ├── window/                 #   主窗口 + 桌面歌词窗口
│   ├── ipc/                    #   IPC 注册
│   └── services/               #   store / database / fileServer / musicServer(4388)
│                               #   / dataServer(4389) / transcode / network / lanInfo
├── preload/                    # 类型安全的 window.api 桥接
└── renderer/                   # 渲染进程（React）
    └── src/
        ├── components/         #   TitleBar / Sidebar / PlayerBar / MusicList / ...
        ├── pages/              #   Home / Albums / AlbumDetail / Favorites / Playlists
        │                       #   / History / Lyric / Transfer / Sync / Settings / DesktopLyric
        ├── stores/             #   uiStore / playerStore / libraryStore（Zustand）
        └── lib/                #   repository（DB 访问）/ lrc（歌词解析）/ const

已复刻的 PC 端功能

• 音乐馆（按企划分组）、专辑、专辑详情
• 播放器（顺序/列表循环/单曲/随机、进度、音量、媒体会话、上一首/下一首）
• 我喜欢、歌单（PC id≤100 / 手机 id>100）、最近播放
• 三语歌词（日/中/罗马音）+ 桌面歌词独立窗口
• WiFi 传歌（二维码配对 + WebSocket 4388 + HTTP 文件下载）
• 数据同步（我喜欢/歌单双向，WebSocket 4389）
• 本地 HTTP 文件服务（端口探测、可配置）
• iOS flac→wav 转码
• 设置：曲库目录、HTTP 端口、主题（深/浅/跟随系统）、强调色
• 无边框窗口（Windows 自定义控制按钮 / macOS 红绿灯位）

与移动端的兼容性设计

• 协议单一来源：src/shared/protocol/commands.ts 定义所有命令字（枚举，禁止裸字符串）， 字符串值与旧移动端保持一致，保证新 PC 端可直接与现有 App 联动。
• 版本协商：version.ts 在保留 transVer=1 兼容的同时引入 minCompatVer + capabilities， 支持向后兼容与能力位扩展。
• 数据结构对齐：领域模型与移动端 Floor 实体一致，降低同步映射成本。
• 移动端重构时可把 src/shared 作为协议对照，甚至用代码生成同步。

开发与构建

npm install                 # 安装依赖（postinstall 会为 Electron 重建原生模块）
npm run dev                 # 开发模式
npm run build               # 类型检查 + 打包
npm run build:win           # 打 Windows 安装包

首次如遇 Electron uninstall，执行 node node_modules/electron/install.js 下载 Electron 二进制； 原生模块（better-sqlite3）如报 ABI 不匹配，执行 npx electron-builder install-app-deps。

待接入（占位/后续）

• OSS data.json 曲库元数据拉取入库（main/services/network.ts 已备 fetchJson，UI 触发待接）
• 断点续传 / 完整性校验 / 配对 token 鉴权（协议 capabilities 已预留）
• 自动更新（electron-updater 接线）、导出 Excel、托盘