星音乐 · star-music

基于 Wails 的 Windows 桌面音乐播放器

聚合多平台音源 · 支持自定义音源脚本 · 歌单与音源云端同步

---

📖 简介

星音乐 PC 端是「星音乐」项目的桌面版本。它把移动端积累的完整业务逻辑（音源调度、歌单管理、播放器、云端备份）整体移植到桌面，并用 Go + Wails 重新实现了移动端受限于浏览器沙箱而做不到的能力：原生窗口控制、跨域请求代理、任意路径文件读写、系统下载、安装包在线更新。

应用内嵌 WebView2 渲染界面，前端依旧是熟悉的 Vue 3 + Vite，Go 只负责「浏览器做不了的那部分」，两端通过 Wails 自动生成的绑定（frontend/wailsjs/）通信。

界面语言为中文，默认绿色清新主题，无边框窗口 + 自绘标题栏。

---

✨ 功能特性

🎵 播放与音源

能力	说明
多平台音源	酷我、酷狗、QQ 音乐、网易云音乐、咪咕 五大平台，外加重命名后的本地音乐
自定义音源	兼容 LX Music 音源脚本协议，可导入 .js 音源脚本，支持多脚本管理与切换
音质选择	flac24bit / flac / wav / ape / 320k / 192k / 128k
播放模式	列表循环、随机播放、顺序播放、单曲循环
歌词	逐行滚动歌词，高亮当前行；支持解析内嵌歌词与外部歌词接口
频谱可视化	播放页频谱动画（模拟频谱，非实时音频分析）
倍速播放	支持变速不变调

🖥️ 桌面体验

• 无边框窗口：自绘标题栏，集成最小化 / 最大化 / 关闭 / 全屏
• 窗口自适应：启动时按当前屏幕可用区域校准尺寸，小屏机器自动收缩，不超出屏幕
• 迷你模式：一键收起为小窗，支持置顶，常驻桌面角落
• 播放队列：独立面板查看与调整待播列表
• 右键菜单：歌曲列表支持右键操作（播放 / 下一首播放 / 下载 / 收藏等）
• 主题系统：多套主题色，支持自定义背景图
• 键盘与交互细节：进度条、音量条、歌词区均做了桌面端适配

☁️ 账号与同步

• 账号登录（本地登录态缓存，code=2 顶号时自动清理并广播状态）
• 歌单与音源云端备份 / 恢复
• 自动备份：开启后，歌单或音源一旦发生变化（listUpdated / customListUpdated / apiSourceUpdated / userApiUpdated），自动在 3 秒防抖 + 30 秒最小间隔内静默上传云端；失败不打扰用户，仅在日志中记录

🛠️ 系统能力（Go 侧）

• 跨域请求代理 HttpRequest：前端所有音乐 API 请求经 Go 转发，彻底绕开 WebView2 的 CORS 限制
• 原生文件选择：音源脚本、文本、图片、目录选择器
• 文件保存 / 导出：文本、JSON、图片；支持下载文件到指定目录
• 系统下载 DownloadFile：流式下载到磁盘，支持进度回调
• 资源管理器集成：ShowInFolder 定位文件、OpenPath 打开路径
• 剪贴板读写：一键复制日志、分享链接
• 运行日志：前端日志落盘 WriteClientLog，便于排查问题
• 在线更新：DownloadUpdate（带 MD5 校验）→ ApplyUpdate 静默调起安装包
• 彩蛋：内置隐藏小游戏（StarJumpGame），自己去发现 😉

---

🧱 技术栈

层	技术
桌面容器	Wails v2.16.0（Go 宿主 + WebView2 运行时）
后端语言	Go 1.25.0
前端框架	Vue 3.5（<script setup> 组合式 API）
构建工具	Vite 5.4 + @vitejs/plugin-vue
打包	NSIS（makensis），产物为单文件安装包
前端嵌入	//go:embed all:frontend/dist，静态资源编译进二进制

---

📁 目录结构

pc/
├── app.go              # Go 侧全部能力（窗口、文件、下载、HTTP 代理、更新…）
├── main.go             # Wails 应用入口、窗口参数、WebView2 数据目录
├── wails.json          # Wails 构建配置（名称 / 版本 / 作者 / 产物名）
├── go.mod / go.sum
├── build/              # 图标、Windows 资源、NSIS 安装脚本
│   ├── appicon.png
│   └── windows/
│       ├── icon.ico
│       └── installer/
│           ├── project.nsi        # 安装向导（含中文文案，需 UTF-8 BOM）
│           ├── wails_tools.nsh    # 由 Wails 每次构建生成，勿手改
│           └── license.txt
├── scripts/
│   ├── build-installer.cjs  # 一键打包安装版（自动补 makensis / BOM）
│   ├── prepare-nsis.cjs     # NSIS 脚本预处理
│   └── gen-icons.cjs        # 图标生成
└── frontend/                # Vue 3 前端
    ├── index.html
    ├── vite.config.js
    └── src/
        ├── App.vue
        ├── main.js
        ├── views/           # SplashView / SearchView / PlaylistView / PlayDetailView
        │                    # AccountView / SettingsView / AboutView
        ├── components/      # AppTitleBar / AppSideBar / PlayerBar / MusicList / LrcView
        │                    # Visualizer / PlayQueue / MiniPlayer / Ui* 通用组件 …
        ├── composables/     # usePlayer / useTheme / useQuality / useShell / useFeedback
        ├── common/          # 业务核心：player / playlist / search / api-source / data
        │                    # account / setting / event / constants / update
        │                    # music-sdk/（各平台接口实现）
        │                    # user-api/（音源脚本沙箱、执行器、日志）
        ├── uni/             # 平台适配层（native.js 桥接 Go 能力）
        ├── style/tokens.css # 设计令牌
        └── wailsjs/         # Wails 自动生成的 Go 绑定（勿手改）

---

🚀 快速开始

运行环境

开发 / 构建

• Windows 10 1809 及以上（WebView2 所需）
• Go 1.25+
• Node.js 18+
• Wails CLI：go install github.com/wailsapp/wails/v2/cmd/wails@latest
• NSIS（仅打安装包需要）：winget install --id NSIS.NSIS -e

最终用户

• Windows 10 / 11，系统自带 WebView2；若缺失请安装 WebView2 Runtime（Evergreen 版）

开发调试

cd pc
wails dev

热重载启动，前端改动即时生效，Go 侧改动自动重新编译。

只想调前端？也可以 cd frontend && npm install && npm run dev，但缺少 Go 能力（HTTP 代理、文件选择等）相关功能不可用。

构建发行版

cd pc

# 仅编译二进制（产物：build/bin/starmusic.exe）
wails build

# 编译并生成 NSIS 安装包（产物：build/bin/starmusic-pc-<版本>-Setup.exe）
wails build -nsis

也可以使用项目自带的一键脚本（它会自动定位 makensis、并给 project.nsi 补 UTF-8 BOM，避免中文乱码）：

node scripts/build-installer.cjs

---

🎼 关于音源脚本

应用不内置任何音源脚本，音源能力全部来自用户自行导入的脚本，遵循 LX Music 音源脚本协议：

• 脚本运行在隔离沙箱中，需提供 globalThis.lx 对象，包含 request / on / send / utils 等方法
• 支持的动作：musicUrl、lyric、pic（搜索由内置实现兜底）
• 导入方式：设置 → 音源 → 导入音源，选择本地 .js 文件
• 调度时会同时传入标准参数（info.type、info.musicInfo）与扁平参数（info.source、info.songId、info.quality），以兼容不同脚本写法

请仅导入来源可信的脚本。脚本拥有发起网络请求的能力，其行为由脚本作者决定。

---

💾 数据目录

应用数据统一存放在：

%AppData%\starmusic-pc\
├── webview\     # WebView2 用户数据（localStorage / IndexedDB / Cache）
└── ...          # 日志、配置、下载记录等

在 设置 → 诊断 中可直接打开配置目录，或复制运行日志用于反馈问题。

---

❓ 常见问题

多为缺少 WebView2 运行时。安装 WebView2 Runtime 后重试。

音源脚本失效或被目标平台限流。请在 设置 → 音源 中更换 / 更新脚本，并到 诊断 → 运行日志 查看具体报错。

封面来自音源接口返回的图片地址，部分平台会做防盗链。应用已在内置实现中做兼容处理，若仍异常通常是该接口临时变更。

自动备份是「本地 → 云端」的单向上传，开启后本地数据会覆盖云端备份。请确认本地歌单已是想要保留的版本再开启。

project.nsi 必须带 UTF-8 BOM，否则 NSIS 会按系统 ANSI 代码页解码。使用 node scripts/build-installer.cjs 打包可自动处理。

---

⚠️ 免责声明

• 本项目仅供个人学习与技术研究使用，不得用于任何商业用途。
• 应用本身不提供、不存储、不分发任何音乐内容。所有内容均来自用户自行导入的音源脚本及其指向的第三方服务。
• 使用本项目产生的任何后果由使用者自行承担。请支持正版音乐，尊重版权方权益。
• 如有侵权，请联系删除。

---

📄 许可证

本项目基于 GPL-3.0 协议开源。

仰望星辰工作室 出品

Made with ❤️ and Wails