Nekosonic-Music/CHANGELOG.md

v0.9.0

本次版本为音源系统与播放器核心重构版本，新增多音源融合系统、歌曲标签体系、搜索建议、播放器稳定性优化等重大功能。

✨ 新功能

🎵 多音源系统

• 可配置多音源：支持配置多个音源（波点、酷狗、酷我），可独立启用/禁用/排序，支持自定义音源扩展
• 音质优化：酷我音源支持更高音质播放，提供更多音质选择
• 多源自动切换：歌曲播放时自动尝试多个音源，版本一致性匹配（原版/DJ/Live/混音）
• 多源融合搜索：搜索结果聚合多个音源，按歌名+歌手组合去重，提供更多选择

🏷️ 歌曲标签体系

• 智能标签显示：自动识别并显示歌曲标签（音质/版本/音源），提供清晰的歌曲信息展示
• 权限信息聚合：统一管理歌手、歌单、专辑、每日推荐、收藏页的歌曲权限信息

🔍 搜索体验优化

• 实时搜索建议：输入时自动显示搜索建议，支持中文拼音输入，120ms 防抖优化
• compositionend 支持：正确处理中文输入法的组合输入过程，实时响应
• 浮层定位优化：Teleport + fixed 定位，避免被父容器裁剪，显示更完整

🎨 播放器改进

🎧 核心播放优化

• 网络流 seek 支持：sharedBuffer 下载完成后支持拖动进度条跳转（byte_len 可用）
• 切歌流程优化：停止旧歌曲播放后再加载新歌曲，进度条正确归零，避免音频叠加
• 加载状态可视化：切歌时按钮显示加载状态并禁用，提供清晰的交互反馈
• tick generation 防竞态：无 tick 时不覆盖新歌曲位置，避免播放位置跳变

🖥️ 系统媒体控制

• 跨平台媒体键支持：系统媒体控制集成（Windows/Linux/macOS），支持媒体键、通知栏、锁屏控制
• Windows hwnd 就绪检查：增加窗口句柄就绪检查，避免 panic，提升稳定性

v0.8.1

🐛 修复

• 关闭到托盘不生效：点击关闭按钮选择「最小化到托盘」或「直接退出」时，窗口未隐藏/退出。原因是 capabilities/default.json 缺少 core:window:allow-hide 权限，前端调用 currentWindow.hide() 被 Tauri 2 权限系统静默拦截。补齐 allow-hide 与 allow-show 权限

v0.8.0

本次版本为架构重构与交互升级版本，涵盖皮肤系统、详情页架构、侧边栏交互、播放器稳定性、底层模块拆分等方面的系统性优化。

✨ 新功能

• 皮肤系统重构：新增 skins.ts 模块，定义 SkinColors 色板（bg/surface/subtle/muted/emphasis/content×4/line×2/accent×4/danger×2/warning/info 共 19 个语义色），通过 applySkinColors() 写入 CSS 变量到 document.documentElement。内置 14 套预设皮肤（7 色 × 深浅），支持自定义皮肤（颜色 + 壁纸 + 模糊度 + 透明度）
• 设置页皮肤模块：Settings.vue 新增「皮肤」分区——深浅外观切换、7 色主题色选择、自定义皮肤网格（带壁纸预览）、皮肤编辑器（19 个颜色色板 + 壁纸选择 + 模糊/透明度滑杆）。壁纸通过 Rust 命令读取本地图片转 data URL 渲染
• 顶栏导航：新增 TopBar 组件，集成前进/后退按钮和搜索框，前进后退按钮仅在与主内容区对齐的位置显示，搜索可直接在顶栏输入，无需再点击搜索选项
• 可折叠侧边栏：侧边栏支持展开/折叠/抽屉三种模式，折叠时仅显示图标，窗口过窄自动切换为抽屉模式。折叠/展开触发条采用 SPlayer 风格的双竖条设计，hover 时通过 ±12deg 旋转形成方向箭头（参考 naive-ui n-layout-toggle-bar）
• 折叠态歌单浮层：侧边栏折叠后，hover「我的歌单」「收藏的歌单」图标弹出浮层显示歌单列表，通过 Teleport 渲染到 body 避免被裁剪。浮层高度动态计算，底部永不越过 PlayerBar
• 首页内容扩展：首页新增「新歌速递」「热门歌手」「新碟上架」三个区块，配合原有的「推荐歌单」「每日推荐」「热门歌单」，共 6 个内容区块
• 通用卡片组件：新增 PlaylistCard、ArtistCard、AlbumCard、SectionHeader、CardGrid 五个可复用卡片组件，统一封面、标题、副标题、悬浮播放按钮的展示风格
• 虚拟歌曲列表：新增 VirtualSongList 组件，复用 SongListItem 并支持自定义配置
• 推荐 API：后端新增 personalized、personalized_newsong、top_artists、top_song、album_newest 五个 Tauri 命令，前端新增 rec.ts API 模块
• 详情页统一架构：新增 DetailLayout 组件，统一歌单/专辑/歌手三个详情页布局——头部常驻 + 内容独立滚动 + 滚动触发紧凑态（参考 SPlayer ListDetail/useListScroll）。absolute;inset:0 脱离主滚动流，flex 列布局让 header flex-shrink:0 不被带走，content flex-1 min-h:0 独立滚动
• 紧凑态动画：滚动列表超过 10px 时触发头部收缩，封面/标题缩小、元信息折叠隐藏、按钮缩小，所有过渡统一 cubic-bezier(0.4, 0, 0.2, 1) 0.3s，参考 SPlayer .small 类行为
• 歌曲/评论 tab 切换：三个详情页头部均加入歌曲/评论（或热门歌曲/专辑）tab 切换。songs 用 v-if 仅激活时渲染，comments 用「首次激活后保活」模式（v-if 控制挂载 + v-show 控制显示），保留滚动位置且不提前发起评论 API 请求
• 专辑模糊搜索：专辑详情页头部加入模糊搜索框，按歌名/歌手/专辑名实时过滤歌曲列表，播放全部时只播过滤结果
• 本地音乐多文件夹管理：本地音乐支持添加多个扫描文件夹，每条可独立启用/禁用/移除，扫描时跳过禁用文件夹

🐛 修复

• 个性化推荐错乱：首页聚合缓存在未登录时生成，登录后未清除导致「依据口味推荐」显示的全站数据。改为登录/登出时清除首页缓存并重新加载，区分登录态调用 recommend_resource（个性化）和 personalized（全站）
• 播放竞态条件：切歌、播放/暂停、拖动进度条等异步操作可能产生竞态冲突。引入序列号（_playSeq）和状态锁（_switchingSong）防护
• 拖动进度条暂停修复：seek 过程中状态不一致导致播放/暂停混乱
• 折叠态歌单不可用：折叠时歌单图标用 popover 浮层但被 overflow-y-auto 容器裁剪，导致「空有两个按钮没有实际作用」。改用 Teleport + fixed 定位渲染浮层
• 折叠态浮层被 PlayerBar 遮挡：浮层原用固定 max-h-60，触发图标靠下时底部歌单被 PlayerBar 盖住。改为按视口高度动态计算 maxHeight，浮层底部永不越过 PlayerBar 顶部
• 详情页头部被滚走：原实现头部和列表在同一滚动容器中，向下滚动时封面/标题/按钮全部滚走。重构为 DetailLayout 后头部 flex-shrink:0 常驻顶部，列表独立滚动
• 评论 tab 提前加载：原 PlaylistDetail 用 v-show 包裹 CommentSection 导致组件挂载即触发评论 API。改为懒加载 + 保活模式，首次切到评论 tab 才发起请求
• 切换 tab 紧凑态卡死：评论/歌曲高度差异大，切换 tab 后紧凑态可能卡在错误状态。新增 watch(currentTab) 调用 resetScroll() 重置滚动和紧凑态
• 侧边栏折叠按钮非箭头：原实现用单根竖条倾斜，hover 时呈斜线非箭头。改为 naive-ui 双竖条方案：两根 4×38px 竖条 4px 重叠，旋转 ±12deg 形成 < 或 > 箭头
• 箭头重叠区颜色加深：opacity 应用到单个竖条导致重叠区颜色叠加变深。改为 opacity 应用到容器（默认 0.5，hover 1.0），竖条使用纯色
• 歌词截断与抖动：长歌词被 whitespace-nowrap 截断。移除该属性并加 word-break:break-word + overflow-wrap:anywhere；活跃行字号变化导致抖动，锁定 line-height:1.5
• 滚动条主题色丢失：之前误将 --c-content-3 用作 thumb 颜色。从 git 历史恢复原实现：hover 容器显示 --c-muted，hover thumb 变 --c-emphasis，主题切换自动跟随
• 专辑标题字号变化抖动：从 30px 切到 22px 时容器高度变化导致布局抖动。固定 line-height:1.3 + min-height:39px，过渡期间容器高度恒定
• AlbumDetail 重复绑定滚动：keep-alive 首次挂载时 onMounted 和 onActivated 都触发 bindScroll()。重构后 DetailLayout 自管滚动监听，AlbumDetail 移除全部 bindScroll/unbindScroll 逻辑

🎨 变更

• 侧边栏布局重构：侧边栏改为全高布局，TopBar 仅在主内容区上方，前进/后退按钮与主内容对齐。侧边栏顶部新增 Logo 占位区（与 TopBar 等高）
• 侧边栏透明化：移除侧边栏和顶栏的不透明背景色，仅靠一条 40% 透明度的边框线分隔，壁纸/主题色从底层透出，实现「半隐藏」视觉
• 文字不乱跳：侧边栏展开/折叠过渡时，菜单文字改为 max-width + overflow-hidden + whitespace-nowrap 平滑过渡，不再因宽度变化导致换行乱跳
• 顶栏透明化：TopBar 移除背景色，加底部细线与侧边栏右边框呼应
• 专辑封面立体感：专辑详情页封面加入模糊阴影背板（blur(12px) opacity(0.6) scale(0.92,0.96)）和顶部渐变遮罩，紧凑时遮罩淡出，参考 SPlayer .cover-shadow/.cover-mask
• 漫游抽屉外观一体化：RoamDrawer 改用 backdrop-blur-xl 配合皮肤系统色板，外观跟随当前皮肤
• 全局样式精简：style.css 精简约 298 行，原硬编码色值迁移至皮肤 CSS 变量系统

⚡ 优化

• 音频模块拆分：将单文件 audio.rs（1228 行）拆分为 audio/ 目录下 8 个模块（mod/buffer/commands/controller/decoder/device/download/output），提升可维护性
• 状态管理职责分离：将单一 player store 拆分为 player、liked、recent、ui 四个职责单一的 store
• 类型定义抽取：Song 等类型定义抽取到 types/song.ts
• API 层领域分离：将 api.ts（225 行）拆分为 api/ 目录下 song/playlist/artist/album/search/rec/comment/device 等领域模块，index.ts 作向后兼容层
• 两级缓存：页面数据和歌词实现 L1 内存 + L2 localStorage 两级缓存，带 TTL 和配额管理
• 设置迁移：设置数据引入版本号和迁移机制（migrations/settingsMigrations.ts），支持未来 schema 变更
• AlbumDetail 重构接入 DetailLayout：原本自行实现 absolute 布局 + isCompact + 滚动监听，与 DetailLayout 逻辑重复。重构后改用 DetailLayout 组件 + slot prop，删除约 100 行重复代码（onScroll/bindScroll/unbindScroll/resetScrollState/listScrollRef/rafId 等）
• 窗口控制逻辑抽取：TitleBar 与 TopBar 重复实现 minimize/toggleMaximize。抽取为 composables/useWindowControls.ts 共用
• 溢出检测抽取：PlaylistDetail 与 ArtistDetail 重复实现 checkDescOverflow。抽取为 utils/dom.ts 的 checkOverflow 函数共用
• 骨架动画全局化：@keyframes pulse 原在三个详情页分别定义，移至全局 style.css 共用
• 死代码清理：删除未使用的 pageCacheDelete（与 pageCacheInvalidate 重复）、getAlbumDisplay、stores/player.ts 中冗余的 Song/PlayMode re-export
• 错误日志可读性：9 处裸 console.error(e) 添加描述性前缀（如 console.error('获取歌单详情失败', e)），方便定位
• AlbumDetail watcher 合并：原本监听 route.params.id 的两个 watcher（一个重置状态、一个 fetchAlbum）合并为一个
• 新增后端命令：read_image_as_data_url（读取本地图片转 data URL，供壁纸预览使用）、show_item_in_folder（在文件管理器中打开文件位置）

v0.7.0

✨ 新功能

• 音乐云盘：新增云盘页面，可浏览、播放云盘中的歌曲，查看文件详情（文件名、大小、比特率、上传时间），删除云盘歌曲，查看存储空间使用情况
• 云盘上传：支持上传本地音频文件到云盘，上传过程显示实时进度，支持 mp3/flac/wav/ogg/aac/m4a 格式
• 下载音乐：本地音乐拆分为「本地音乐」和「下载音乐」两个独立页面，下载音乐只显示通过应用下载的歌曲
• 本地音乐多文件夹：本地音乐支持添加多个扫描文件夹，通过三点按钮+弹窗管理文件夹路径
• 歌手关注：歌手详情页新增关注/取关按钮，关注状态在离开页面后不会丢失
• 粘性导航栏：页面滚动较深时顶部自动显示返回按钮和功能按钮，渐变模糊效果，不影响阅读
• 骨架屏加载：首页、歌单、歌手、专辑、云盘等多个页面加载时显示骨架占位动画，不再只有"加载中"文字

🐛 修复

• 网络较差时播放启动超时，音乐实际已开始播放但界面仍显示暂停
• 全屏漫游抽屉打开时点击评论按钮无法切换到评论页
• 关闭漫游抽屉后再打开，始终显示评论而非歌词
• 歌手详情页关注后离开再回来，关注状态丢失
• 切歌时偶尔触发上一首歌的播放结束事件导致异常
• 评论点赞无限叠加（改为服务端状态驱动）
• 播放栏进度条上方多余分隔线

🎨 变更

• 歌手详情页头像改为圆形，简介从独立标签页移至头部内嵌显示，溢出时可展开查看完整介绍
• 歌单详情页描述溢出时显示"查看完整介绍"按钮
• 首页推荐和排行榜加载失败时显示重试按钮，支持分别重试
• 多个页面的返回按钮统一为粘性导航栏组件
• 消息提示增加去重和数量限制，避免重复弹出

⚡ 优化

• 页面切换更流畅，路由全部改为懒加载
• 页面缓存管理优化，30 秒未访问自动释放，多级跳转时保留导航链上的页面，「我喜欢的音乐」常驻缓存
• 本地音乐扫描不再阻塞界面导航
• 应用启动不再等待网络请求完成

v0.6.0

✨ 新功能

• 亮色主题：新增浅色外观模式，支持深色/浅色切换，7 种主题色各有对应亮色变体
• 封面主色背景：全屏漫游抽屉背景自动提取封面图主色调，沉浸感更强；抽屉打开时底部播放栏也跟随封面主色，视觉融为一体
• 发现页重做：支持多类型搜索（歌曲/歌手/专辑），输入时自动显示搜索建议，搜索历史和热门搜索
• 漫游增强：全屏抽屉支持歌词/评论切换，播放栏新增减少推荐按钮
• 减少推荐：FM 模式下可标记"不推荐这首歌"或"不推荐这个歌手"，后续不会再收到类似推荐
• 列表风格统一：正在播放的歌曲序号位置显示跳动动画，鼠标悬停显示播放图标；红心/下载等图标统一使用图标库

🐛 修复

• 专辑页艺术家过多时窗口缩小会竖排显示，现在支持自动换行
• FM 播放时退出登录后首页仍可点击下一首
• 本地音乐播放时缓冲进度条未重置
• 亮色主题下多处文字看不见
• 退出 FM 模式时状态未正确清理
• 暗色模式下关闭抽屉时播放栏短暂闪烁亮色

🎨 变更

• 移除播放列表按钮上的数字角标
• 主页每日推荐和 FM 卡片标题固定为白色，不随主题变化

🧹 清理

• 内部代码优化和冗余清理

v0.5.1

🐛 修复

• 修复页面缓存不刷新的问题：切换回已缓存的页面时数据永远不更新，现在超过 5 分钟会自动重新加载
• 修复本地音乐页面空列表时刷新按钮不显示的问题
• 修复修改下载路径后本地音乐列表不更新的问题，现在会自动刷新
• 修复私人 FM 播放约二三十首后循环重复的问题：新增听歌打卡上报，服务端推荐不再重复
• 修复歌词界面切换翻译开关时歌词未居中的问题
• 修复 Linux 下从外部控制暂停时进度条跳回 0 的问题：MPRIS 现在正确报告播放进度位置

⚡ 优化

• 私人 FM 预取队列优化，队列剩余不足时自动后台拉取下一批

v0.5.0

✨ 新功能

• 蓝牙耳机/键盘媒体键控制：支持通过蓝牙耳机按钮、键盘媒体键、系统通知栏/锁屏面板控制播放、暂停、切歌（Windows / Linux / macOS）
• 网络状态检测：断网和恢复时弹出提示，网络恢复后自动重新加载页面内容
• 音量记忆：关闭应用后音量设置不丢失，下次打开自动恢复
• 歌词翻译：支持显示歌词翻译，可在漫游页面切换开关
• 登录页优化：已登录用户访问登录页会自动跳转回首页

🎨 变更

• 默认主题色改为天蓝色
• 全局快捷键显示顺序调整为 Ctrl + Alt（之前是 Alt + Ctrl）
• 快捷键显示优化：按键名更简洁，如 KeyP 显示为 P
• 页面缓存优化：更多页面切换时保留状态，窗口隐藏时自动释放
• 登录页等待确认时的文字颜色修正

🐛 修复

• 手动检查更新时，之前跳过的版本现在会正常弹出更新提示
• 点击正在播放的歌曲无法恢复播放的问题
• 部分内部类型定义问题导致的潜在隐患

⚡ 底层优化

• 音频播放引擎全面重构，播放更稳定
• 后端 API 调用模式统一，代码更易维护
• 歌曲数据模型统一，各页面显示更一致

v0.4.1

添加音频输出外设选择

v0.4.0

✨ 新功能

• 添加歌曲的艺术家入口，歌曲的艺术家现可点击查看其他歌曲、专辑和介绍
• 添加歌曲的评论查看功能

🐛 修复

• 修复私人漫游自动播放下一首调用多次问题

⚡ 优化

• 优化播放逻辑，歌曲列表在点击时候不再单首累加，而是直接获取当前列表所有的歌曲作为播放内容

v0.3.0

✨ 新功能

• 本地音乐页面：支持浏览、播放本地歌曲，横向菜单添加「从磁盘删除」功能
• 下载系统：支持下载歌曲到自定义路径，保存完整元数据（封面/专辑/时长）
• 封面补全：本地音乐缺少封面时尝试从网易云 API 获取
• 更新信息：添加查看最新版更新日志按钮
• 下载路径：支持自定义下载路径
• 本地音乐：支持本地音乐播放
• 下载提示：下载进度与完成提示
• 快捷键绑定：支持自定义全局和本地快捷键（播放/暂停、上一首/下一首、音量调节）

🐛 修复

• 修复私人漫游播完一首歌后跳三首的问题
• 修复全屏漫游抽屉和漫游页面无封面歌曲显示破损图片
• 修复 PlayerBar 无封面歌曲显示破损图片
• 修复播放网络歌曲时进度条先走但无声音

⚡ 优化

• 流式播放：边下载边播放，缓冲 64KB 后即刻开始，无需等待完整下载

v0.2.0

🎵 播放

• 优化私人漫游（个人 FM）功能
• 新增歌曲喜欢/取消喜欢红心
• 新增播放历史本地记录（最近 200 首）

📋 歌单

• 修改逻辑 我的歌单 不再显示收藏按钮
• 收藏歌单支持取消收藏
• 实现我的音乐功能
• 实现历史播放记录功能

🎨 外观

• 全局复选框与选择框优化
• 部分UI优化，统一风格

🖥️ 窗口

• 关闭窗口弹出确认弹窗：最小化到托盘 / 退出程序
• 支持"不再询问"选项，可在设置中修改
• 修复退出时 WebView2 报错（Error 1410）
• 修复歌词抽屉全屏时候顶栏无法接收事件问题

💾 持久化

• Cookie 存储迁移至 Tauri app_data_dir
• 播放历史持久化到 localStorage

⚙️ 其他

• 添加设置功能
• 关于添加链接可直接访问仓库

v0.1.0

Nekosonic 是一款基于 Tauri 2 + Rust 的跨平台桌面音乐播放器，音源主要来自网易云音乐，开箱即用。