lx-music-desktop 2.12.2 发布说明解读：歌单搜索排序优化、四项缺陷修复与 changelog 发布流水线

本文以 publish/changeLog.md 中 lx-music-desktop 2.12.2 版本的发布说明为主体，逐条解读该版本的优化与修复内容；同时结合仓库中 publish/ 下的发布脚本与 CHANGELOG.md 的最终形态，说明这份草稿式 changelog 是如何被版本化、落库到仓库，并最终在应用内的更新弹窗中呈现给用户的完整链路。读完本文，你可以掌握该版本的全部变更点，以及维护一个 Electron 项目发布日志的自动化套路。

2.12.2 版本核心变更

publish/changeLog.md 是即将发布（或刚发布）版本的变更说明草稿，其内容对应 CHANGELOG.md 中 2.12.2 条目（2026-05-01 发布）。本节完整继承该文档的正文结构。

项目动态：Any Listen 桌面版发布说明

版本说明开头先交代了作者的新项目动态：

我们很高兴地宣布新项目 Any Listen 的桌面版已发布，目前已支持列表跟随本地文件自动更新、加载并播放 WebDAV 上的歌曲等功能，更多功能仍在积极开发中，桌面版与 Web 版将同步更新。对于有播放本地音乐或播放服务器上音乐需求的人可以试试，若遇到任何问题可以发 issue 反馈。

这是对目标用户（有本地音乐或服务器音乐播放需求的用户）的定向提示，属于版本说明中“公告”性质的内容，而非 lx-music-desktop 自身的功能变更。

优化

• 优化歌单内歌曲搜索结果排序（#2734）

该项对应 src/renderer/views/List/MusicList/useSearch.js 所在的“我的列表-歌单内歌曲搜索”场景：用户在歌单详情页内对歌曲做列表内搜索时，搜索结果的排列顺序得到了优化。此前 v1.0.0 版本的 CHANGELOG.md 中已提到过“对我的列表歌曲搜索结果进行相似度排序”，2.12.2 是在该排序机制上继续调优。

修复

• 修复桌面歌词的“鼠标移入歌词区域时提高透明度”设置不稳定的问题（#2679，贡献者 @Little100）
• 修复某些情况下可能播放没有声音的问题（#2693）
• 修复 tx 搜索结果显示异常的问题（#2753）
• 修复音乐名称和歌手信息格式化问题（#2733）

四条修复分别覆盖桌面歌词模块（对应 src/renderer-lyric/ 独立窗口）、播放器无声问题、tx 音源搜索展示（对应 src/renderer/utils/musicSdk/tx/musicSearch.js 所在的音源适配层）以及音乐元信息格式化（对应 src/common/utils/musicMeta/ 等元数据工具）。值得注意的是，该版本把“音乐名称和歌手信息格式化”单独作为一条修复项，这类信息最终会体现在播放栏、歌曲列表与下载文件的命名中。

其他：Electron 运行时升级

• 更新 Electron 到 40.8.3

升级 Electron 对桌面端应用意味着 Chromium 内核与 Node.js 运行时同步前进，通常用于跟进安全补丁与底层修复。需要注意一个版本细节：发布说明记录的是 40.8.3，而当前仓库 package.json 的 devDependencies 中声明的 electron 版本为 40.9.2。两个值同属 Electron 40.x 系列，差异说明发布说明撰写时点与依赖最终锁定版本之间存在时间差，阅读版本记录时可以把“运行时处于 Electron 40.x”作为该版本的事实结论。

从草稿到仓库：changelog 的发布流水线

publish/changeLog.md 并不是给人直接阅读的终点，而是发布流水线的“输入原料”。仓库在 publish/ 目录下提供了一套基于 Node.js 的版本发布脚本，将这份草稿与 publish/version.json、CHANGELOG.md 三个产物联动更新。

三个数据文件与职责

文件	角色	说明
publish/changeLog.md	输入	新版本的变更说明草稿，发布时整体读入
publish/version.json	输入 + 输出	记录当前 version、desc 与 history 数组（历史上每个版本的说明快照），运行时被更新弹窗消费
CHANGELOG.md	输出	仓库内的完整变更日志，2240+ 行，覆盖从 0.1.0 到 2.12.2 的全部版本，头部声明遵循 Keep a Changelog 风格与语义化版本

从 publish/version.json 的实际内容可以看到，2.12.2 的 desc 字段与 changeLog.md 正文一致（仅剥离了 Markdown 标题标记），其 history 数组则按时间倒序保留了 2.12.1、2.12.0、…… 直至 0.1.0 的每一个版本的完整说明——这正是“草稿 → 快照”机制的落盘结果。

发布脚本的执行流程

package.json 中注册了发布入口：

"publish": "node publish"

入口脚本 publish/index.js 的执行顺序为：

1. 调用 publish/utils/updateChangeLog.js，默认版本号为当前 package.json 的 version（当前为 2.12.2），也支持通过命令行第一个参数指定新版本号（如 node publish 2.13.0）；
2. 读取 publish/changeLog.md 全文作为新版本的 desc，用正则 (?:^|(\n))#{1,6} (.+)\n 剥掉各级 Markdown 标题符号后写入 version.desc；
3. 把 { version: 旧版本号, desc: 旧版说明 } 通过 unshift 压入 version.history 头部，实现“旧版本降级为历史”；
4. 将新版本号同步写回 package.json 与 version.json；
5. 生成 CHANGELOG.md 的新条目。

第 5 步的关键逻辑在 publish/utils/updateChangeLog.js 中：

const log = `## ${newVerNum}\.git$/, '$1')}/compare/v${prevVer}...v${newVerNum}) - ${formatTime()}\n\n${newChangeLog}`
fs.writeFileSync(changelogPath, changeLog.replace(/(## \(?:\d+\.))/, log + '\n$1'), 'utf-8')

即：在 CHANGELOG.md 中第一个 ## [x. 标题前，插入形如 ## [2.12.2 - 2026-05-01 的版本头 + 草稿正文。这里的“上一版本号” prevVer 由 publish/utils/parseChangelog.js 反向解析 CHANGELOG.md 得到，其版本头识别正则为：

line.match(/^\s*##\s+\[?(\d+\.\d+\.\d+)\]?.*?-\s+(\d{4}-\d{2}-\d{2})$/)

要求版本头必须满足 ## [x.y.z] - YYYY-MM-DD 的语义化版本 + 日期格式，若解析不到任何版本号会抛出 CHANGELOG 无法解析到版本号 错误并中断发布。对照 CHANGELOG.md 顶部的实际条目 ## 2.12.2 - 2026-05-01，可以确认该格式约定在仓库中是稳定执行的。

失败回滚机制

publish/index.js 在发布开始时会先对 package.json 与 version.json 做字符串备份（pkg_bak / version_bak），若后续流程抛出异常，会立即把两个文件还原为备份内容，输出“正在还原版本信息 / 版本信息还原完成”。这保证了“版本号已改、日志未写入”的中间状态不会残留在仓库里。

从源码结构看，脚本中还保留了编译资源、打包资产、创建 Release 等被注释掉的步骤（compileAssets、packAssets、githubRelease 等），可以推断当前版本的发布流程已收敛为“纯日志与版本号更新”，而构建与产物分发由 build-config/ 下的 pack.js / build-pack.js（对应 npm run pack:* 系列脚本）独立承担。

应用内消费：更新日志如何呈现给用户

version.json 不只是发布产物的账本，它还被打包进应用、在运行时被读取。src/renderer/components/layout/UpdateModal.vue 与 src/renderer/components/layout/ChangeLogModal.vue 都直接消费 versionInfo.newVersion.history：

• ChangeLogModal.vue 以 [{ version: 新版本号, desc: 新版本说明 }, ...history] 拼装出“含当前版本在内”的历史列表，并按版本号比较（compareVer）过滤出用户需要阅读的版本区间后逐条渲染；
• UpdateModal.vue 在发现新版本时展示更新说明，当 history.length >= 2 时还会给出可忽略的提示（update__ignore_tip），避免用户在多个连续小版本间被反复打扰。

这条链路解释了为什么 changeLog.md 的文案要写得“面向最终用户”：它既进入仓库的 CHANGELOG.md（供开发者与社区查阅），又原样进入 version.json（供应用内弹窗渲染）。而触发更新检查的主进程侧逻辑在 src/main/modules/winMain/autoUpdate.ts，其中 autoUpdater.autoDownload 会读取 common.tryAutoUpdate 设置决定是否自动下载，update-available 等事件通过 WIN_MAIN_RENDERER_EVENT_NAME 转发给渲染进程驱动上述弹窗。

维护参考：撰写下一份 changeLog.md 的约定

基于现有草稿与历史条目的格式惯例，下一版本的 publish/changeLog.md 应遵循以下结构，发布脚本与 CHANGELOG 格式对其有隐式约束：

1. 可选公告段：版本说明开头可以是面向用户的公告文本（如 Any Listen 动态），这部分会被原样保留进 desc；
2. 分节标题：使用 ### 新增、### 优化、### 变更、### 修复、### 其他 等三级标题组织条目，历史条目中这些分节长期保持稳定；
3. 条目规范：每条以 - 列表项书写，涉及 issue 或 PR 的修复应附编号（如 (#2734)），有社区贡献时标注贡献者（如 @Little100）；
4. 格式兼容：正文中的标题行只使用 # 级 Markdown 标题，因为发布脚本剥离标题的正则按 #{1,6} 前缀处理；版本头本身（## [x.y.z] - YYYY-MM-DD）不需要手写，脚本会自动生成。

完成撰写后执行 npm run publish（可选传入新版本号），脚本会一次性完成版本号递增、历史快照、CHANGELOG.md 条目插入四件事，失败时自动回滚——这就是 lx-music-desktop 发布日志从一份十几行的 Markdown 草稿长成 2200 多行 CHANGELOG.md 的完整机制。