企业官网建设流程全解析

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/SPlayer

SPlayer 是一个基于 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++ 桌面开发组件）：

默认只构建当前架构，追加参数可同时出 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-lyrics（AMLL），封装在 LyricPlayer.vue 与 AMLyric.vue，实现逐字（YRC）高亮与卡拉 OK 式滚动；
• 多格式解析：src/utils/lyric/ 下parseLrc.ts（LRC）、parseQrc.ts（QRC）、parseTTML.ts（TTML 字幕）三类解析器，另有字体配置与敏感词过滤（lyricProfanity.ts、lyricStripper.ts）；
• 桌面与任务栏窗口：桌面歌词由独立窗口承载，界面在 DesktopLyric/index.vue，窗口生命周期在 lyric-window.ts 中管理；Windows 任务栏歌词还有专门的 Rust 策略模块native/taskbar-lyric/。

样式、位置、字号均可自定义，歌词翻译与缓存也在这条链路上完成。


本地音乐库：扫描、分类与标签编辑

想把硬盘里的音乐纳管时，LocalMusicService.ts 负责目录扫描与分类，数据持久化在 LocalMusicDB.ts（better-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 }格式，常用控制接口如下：

最短验证就两条：

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 原生模块，含系统媒体/Discord（external-media-integration/）、任务栏歌词（taskbar-lyric/）、中文转换 wasm（ferrous-opencc-wasm/）；
• windows/：任务栏歌词的独立渲染页面。

常用命令（对应 package.json scripts）：

如果开发时不关心系统媒体控件、Discord RPC 这些原生能力，设置SKIP_NATIVE_BUILD=true后再执行pnpm dev或pnpm build即可，无需安装 Rust 工具链——Docker 与 Vercel 构建就是这么做的。

使用须知

• 协议：项目基于AGPL-3.0开源，任何修改、演绎或派生作品必须同样采用 AGPL-3.0 并保留原版权信息，条款见 LICENSE；
• 用途边界：部分功能依赖网易云音乐第三方 API 服务，仅供个人学习研究，禁止用于商业或非法用途；
• 维护模式：项目不再主动开发新功能，仍可持续部署使用；新想法请去 SPlayer-Next 项目跟进。

文档速查

【免费下载链接】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