1 条命令上线的 SPlayer跨平台音乐播放器部署、歌词与 Hi-Res 下载全指南【免费下载链接】SPlayer A cross-platform music player with Jellyfin / Navidrome / Emby media server support, word-by-word lyrics, desktop taskbar lyrics, cloud music drive, local library management, audio spectrum visualization and mobile-friendly UI. 简约的跨平台音乐播放器支持逐字歌词、桌面歌词、任务栏歌词、云盘音乐、本地音乐管理及流媒体播放项目地址: https://gitcode.com/GitHub_Trending/spl/SPlayerSPlayer 是一个基于 Vue 3 Electron 的跨平台音乐播放器网页与桌面双形态运行内置桌面歌词、逐字歌词、本地音乐库管理与最高 Hi-Res 的下载能力。本文先用一条 Docker 命令帮你把 Web 版跑起来再按真实听歌场景逐个拆解它的功能实现与二次开发要点。项目速览定位、技术栈与工程分层双形态运行同一套代码既能打包成 Electron 桌面客户端也能作为纯网页版部署到 Docker、Vercel 或自己的服务器技术栈Vue 3 TypeScript Naïve UI Electron状态管理用 Pinia路由用 Vue Router工程分层src/是渲染进程全部页面与业务逻辑electron/main/是主进程窗口、托盘、快捷键、better-sqlite3 本地数据库electron/server/是内嵌的本地 HTTP/WebSocket 服务native/是 Rust 编写的原生模块系统媒体控件、Discord RPC环境要求pnpm 10、Node.js 20默认构建需要 Rust 工具链只跑网页版可跳过当前状态项目已进入维护模式只做必要维护与重大问题修复新功能请转向 SPlayer-Next。快速上手Docker 一键部署 Web 版 对大多数人来说最省心的路径就是 Docker——构建阶段会跳过原生模块运行时自动装好网易云 API 与解锁服务docker build -t splayer . docker run -d --name SPlayer -p 25884:25884 splayer启动后访问http://localhost:25884即可。想加环境变量如解锁音源UNBLOCK_SOURCES、ENABLE_FLAC直接用仓库里的 docker-compose.yml 执行docker-compose up -d更省事。Dockerfile 是两阶段构建node:22-alpine出静态产物nginx:1.27-alpine-slim托管并统一启动。Vercel 免服务器托管vercel.json 已配好构建命令与产物目录out/renderer。差异在于Vercel 是纯静态托管播放器所需的网易云 API 要先单独部署一个兼容服务然后把.env里的VITE_API_URL指过去最后导入仓库即可。服务器 Nginx 托管流程类似 Vercel克隆仓库后pnpm install pnpm build站点目录指向out/renderer再照 nginx.conf 把/api/netease/与/music/unblock/反代到本地 API 服务端口。本地构建与桌面客户端git clone https://gitcode.com/GitHub_Trending/spl/SPlayer cd SPlayer pnpm install cp .env.example .env pnpm build # 仅构建 Web 版要出桌面安装包则按系统选命令产物在dist/目录需要 Rust 工具链Windows 另需 VS Build Tools 的 C 桌面开发组件命令目标平台pnpm build:winWindowspnpm build:macmacOSpnpm build:linuxLinux默认只构建当前架构追加参数可同时出 x64 与 arm64如pnpm build:win -- --x64 --arm64。按场景拆解跟着使用走一遍在线听歌登录、每日推荐与私人 FM当你第一次打开播放器想听在线歌曲时需要先在登录弹窗里扫码或走手机验证码——扫码链路是qrKey()取 key、qrCreate()出二维码、checkQr()轮询结果手机验证码链路是sentCaptcha()发码、loginPhone()提交两者都集中在 src/api/login.ts对应 LoginQRCode.vue 与 LoginPhone.vue。登录后每日推荐落在 DailySongs.vue 页面推荐数据来自 src/api/rec.ts私人 FM 由 src/api/radio.ts 供数据、PersonalFM.vue 呈现云盘音乐的上传、纠正、删除则封装在 src/api/cloud.ts。歌曲页面的评论区与 Comment.vue 配套评论展示样式如截图所示。桌面歌词与逐字高亮 这块能力分三层逐字引擎基于applemusic-like-lyricsAMLL封装在 LyricPlayer.vue 与 AMLyric.vue实现逐字YRC高亮与卡拉 OK 式滚动多格式解析src/utils/lyric/ 下parseLrc.tsLRC、parseQrc.tsQRC、parseTTML.tsTTML 字幕三类解析器另有字体配置与敏感词过滤lyricProfanity.ts、lyricStripper.ts桌面与任务栏窗口桌面歌词由独立窗口承载界面在 DesktopLyric/index.vue窗口生命周期在 lyric-window.ts 中管理Windows 任务栏歌词还有专门的 Rust 策略模块native/taskbar-lyric/。样式、位置、字号均可自定义歌词翻译与缓存也在这条链路上完成。本地音乐库扫描、分类与标签编辑想把硬盘里的音乐纳管时LocalMusicService.ts 负责目录扫描与分类数据持久化在 LocalMusicDB.tsbetter-sqlite3。想改歌名、歌手、专辑或换封面这块由 MusicMetadataService.ts 借助music-metadata直接读写 ID3 等元数据完成。还有个隐藏福利部分无版权歌曲打不开时内置解锁模块 electron/server/unblock/ 会从酷我kuwo.ts、波点bodian.ts等音源做匹配match.ts通过/api/unblock/*接口给出替代播放源。高音质下载单曲到批量最高 Hi-Res 下载链路的主进程实现是 DownloadService.ts前端入口是 DownloadModal.vue单曲下载与歌单批量下载都走这里进度与结果分别在 src/views/Download/ 的downloading.vue和downloaded.vue页面查看。注意最高支持 Hi-Res 音质前提是账号具有相应会员权限。封面主题色自适应切到一首新歌整个界面会跟着封面变色——这就是全站着色。颜色从封面图提取的实现在 src/utils/color.ts再经material/material-color-utilities生成 Material 风格配色预设色在 themeColor.json而 Light / Dark / Auto 三种明暗模式的切换与持久化由 src/stores/setting.ts 统一管理。连接自己的流媒体服务器若你自建了媒体服务器SPlayer 支持 Subsonic 兼容协议Navidrome、Subsonic、Airsonic以及 Emby / Jellyfin 三套适配客户端代码在 src/api/streaming/subsonic.ts、emby.ts、jellyfin.ts配置界面是 StreamingServerConfig.vue支持多服务器管理与自动连接上次使用的服务器。对外连接HTTP API 与 WebSocket 远程控制播放器播放器启动时会在本地起一个服务HTTP 默认http://localhost:25884前缀/api可用VITE_SERVER_PORT改端口冲突时 port.ts 自动换端口WebSocket 默认ws://localhost:25885。HTTP 响应统一为{ code, message, data }格式常用控制接口如下接口作用GET /api/control/play播放GET /api/control/pause暂停GET /api/control/toggle播放/暂停切换GET /api/control/next/prev下一曲 / 上一曲GET /api/control/status版本与环境信息GET /api/control/song-info当前歌曲信息勿高频轮询进度GET /api/netease/*网易云 API 代理GET /api/unblock/*无版权歌曲解锁最短验证就两条curl http://localhost:25884/api/control/toggle curl http://localhost:25884/api/control/song-info需要实时进度就别轮询 HTTP 了——连上 WebSocket 后会先收到welcome随后服务器持续广播status-change播放/暂停、song-change切歌、progress-change约 500ms 一次、lyric-change歌词事件反向控制只需发送{ type: control, data: { command: next } }空闲时用PING/PONG保活。服务端实现在 SocketService.ts。二次开发目录职责与常用命令想动手改代码前先记住这几块目录各管什么src/渲染进程页面、组件、Pinia stores 全部在此electron/main/主进程窗口windows/、IPC 路由ipc/、系统服务services/electron/server/本地 Fastify 服务含网易云代理netease/、解锁unblock/、QQ 音乐qqmusic/与控制接口control/native/Rust napi-rs 原生模块含系统媒体/Discordexternal-media-integration/、任务栏歌词taskbar-lyric/、中文转换 wasmferrous-opencc-wasm/windows/任务栏歌词的独立渲染页面。常用命令对应 package.json scripts命令说明pnpm dev启动开发服务器含原生模块构建与 Vite HMRpnpm build构建 Web 版生产包pnpm build:native只编译native/下全部原生模块pnpm lintESLint 检查pnpm typecheckTypeScript / vue-tsc 类型检查如果开发时不关心系统媒体控件、Discord RPC 这些原生能力设置SKIP_NATIVE_BUILDtrue后再执行pnpm dev或pnpm build即可无需安装 Rust 工具链——Docker 与 Vercel 构建就是这么做的。使用须知协议项目基于AGPL-3.0开源任何修改、演绎或派生作品必须同样采用 AGPL-3.0 并保留原版权信息条款见 LICENSE用途边界部分功能依赖网易云音乐第三方 API 服务仅供个人学习研究禁止用于商业或非法用途维护模式项目不再主动开发新功能仍可持续部署使用新想法请去 SPlayer-Next 项目跟进。文档速查文档内容docs/guide.md使用与部署指南docs/api.mdHTTP API 接口docs/socket.mdWebSocket 控制与事件docs/streaming.md流媒体服务器接入docs/native.md原生插件集成与排障docs/download.md客户端下载docs/troubleshooting/常见系统问题排查【免费下载链接】SPlayer A cross-platform music player with Jellyfin / Navidrome / Emby media server support, word-by-word lyrics, desktop taskbar lyrics, cloud music drive, local library management, audio spectrum visualization and mobile-friendly UI. 简约的跨平台音乐播放器支持逐字歌词、桌面歌词、任务栏歌词、云盘音乐、本地音乐管理及流媒体播放项目地址: https://gitcode.com/GitHub_Trending/spl/SPlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
