lx-music-desktop 更新日志解读：版本规范、发布流水线与兼容性承诺

CHANGELOG.md 记录了 lx-music-desktop 自 2019-08-16 的 0.1.0 版本起、到 2026-05-01 的 2.12.2 版本为止的全部重要变更，累计跨越 100 多个版本。本文以该更新日志为主体，讲清三件事：更新日志遵循的格式规范（Keep a Changelog / 语义化版本 / Conventional Commits）、历次重大版本中真正的技术转折点（存储重构、同步协议、自定义源 API、Electron 升级链），以及这份日志是如何被 publish 目录 中的自动化脚本解析、拼接并写入的。读完你可以掌握：如何解读该项目的兼容性承诺、如何用发布流水线生成新版本日志条目、以及更新日志中提到的启动参数与源码中的对应实现。

更新日志的格式规范

CHANGELOG.md 开头三行声明了整个文件的编写规则：

• 版本号遵循 Semantic Versioning（语义化版本），即 主版本.次版本.修订号 的形式；
• 提交信息约定基于 Conventional Commits；
• 变更日志格式基于 Keep a Changelog 风格。

由此形成了统一的版本条目格式，每个版本占用一个二级标题，由「版本号 + 版本对比链接 + 日期」三要素组成：

## 2.12.2 - 2026-05-01

正文则按固定小节分类，项目中实际出现过的三级标题包括：

小节	含义
不兼容性变更	会导致旧行为失效、需要用户或源开发者注意的破坏性改动，单独置顶强调
新增	新功能、新设置项、新构建形态
优化	性能、交互、文案层面的改进
修复	Bug 修复，普遍附带 issue 编号（如 #2734）与贡献者署名
变更	默认行为或交互逻辑的调整
移除	被删除的功能、音源或构建
开放API变更	2.8.0 曾单列，说明 HTTP 开放 API 的入参出参变化
自定义源的不兼容变更	2.6.0 单列，专门面向第三方自定义源开发者
文档	对已有行为的补充说明（如 1.19.0 对快捷键行为的汇总）
其他	Electron 升级、依赖更新、文案修订等杂项

例如 2.12.2 的条目就是标准的「优化 / 修复 / 其他」三段式：一条歌单内搜索排序优化（#2734）、四条修复（桌面歌词透明度设置 #2679、无声播放 #2693、tx 搜索结果 #2753、歌曲信息格式化 #2733），以及「更新 Electron 到 40.8.3」。值得注意的是 2.12.x 系列每个版本开头还固定附带一段关于衍生项目 Any Listen 的桌面版发布说明，体现了该项目在 2.10.0 起把「项目矩阵动向」也纳入了更新日志的惯例。

关键版本节点：七年演进的主干

2242 行的日志覆盖了 0.1.0 到 2.12.2 的完整历程，下面按技术影响梳理主干节点（均摘自 CHANGELOG.md 对应条目）：

版本	日期	关键内容
0.1.0	2019-08-16	首个版本发布
0.5.0	2019-09-05	封面嵌入、歌词下载、单例应用（禁止多开）
0.6.0	2019-09-21	音乐聚合搜索、代理功能
0.17.0	2020-03-15	多语言（简中/繁中/英语）、-search 启动参数、音频输出设置、热搜词与搜索历史
1.0.0	2020-07-24	桌面歌词、全局快捷键、rpm/pacman 构建、自定义列表、我的列表内歌曲搜索
1.8.0	2021-03-07	自定义源功能、逐字歌词播放（酷狗源）、-play 启动参数；移除虾米源
1.17.0	2022-01-22	Windows「便携模式」（程序目录下存在 portable 目录即用其作数据目录）、Scheme URL 支持、-proxy-server / -proxy-bypass-list 启动参数
1.19.0	2022-03-20	播放详情页、F11 全屏状态、动态主题「道法自然」、kw 源卡拉OK歌词
2.0.0	2023-01-01	重构里程碑：整体迁移到 TypeScript，列表/歌词数据从 JSON 文件迁移到 SQLite3，新增自定义主题、歌单搜索、本地歌曲入列表
2.1.0	2023-02-18	播放速率调整（0.5x–2.0x）、启动时数据库表结构完整性校验（异常时 .bak 备份重建）、版本更新日志弹窗
2.2.0	2023-03-26	数据同步重构，新增客户端模式；独立的数据同步服务端项目发布
2.4.0	2023-09-09	同步协议逻辑变更（要求 PC v2.4.0 / 移动端 v1.1.0 / 同步服务 v2.0.0）；「不喜欢歌曲」功能与同步
2.5.0	2023-09-28	不再支持 Windows 7/8（仅保留专门的 win7 构建），移除 32 位 Windows 支持；Scheme URL 新增播放器控制
2.6.0	2024-02-01	移除所有内置源（因腾讯投诉）；自定义源调用方式变更，API 版本到 2.0.0
2.7.0	2024-04-14	HTTP 开放 API 服务（默认关闭）、在线自定义源导入（http/https 链接）
2.10.0	2025-01-27	Linux 最低要求 GLIBC_2.29；下载按列表名分组；开放 API 增加播放控制接口
2.12.0	2025-11-29	-hidden 启动参数；Any Listen 逐字歌词标签读取与嵌入；开放 API 增加音量/进度/完整歌词接口
2.12.2	2026-05-01	当前最新版本，Electron 40.8.3

从这张表可以看出日志的组织逻辑：功能演进（搜索 → 歌单 → 桌面歌词 → 同步 → 开放 API）以「新增」小节推进，而平台能力变化（Electron 升级、系统支持范围）则被明确标注为「不兼容性变更」或「其他」，让升级用户能提前评估风险。

Electron 升级链与平台兼容约束

更新日志中「其他」小节几乎每个大版本都会记录 Electron 的升级或降级，构成一条完整的运行时演进链：

版本	Electron	备注（摘自日志）
0.18.0	8.2.5
1.0.0	9.1.1
1.17.0	13.6.7
1.15.2	降级至 13.4.0	修复 Windows 7 下播放崩溃
2.0.0	19.1.9
2.4.0	22.3.23
2.6.0	25.9.8
2.8.0	28.3.3
2.10.0	32.3.0	原生库编译要求 C++20，构建镜像由 node:16 换到 node:18
2.12.0	37.6.0
2.12.2	40.8.3

其中 2.10.0 的说明值得展开：由于 Electron 32 之后原生库编译被限制在 C++20 以上，作者尝试在 node:16 镜像中安装 gcc-10 未果，最终将构建镜像更新到 node:18，直接后果是 Linux 系统至少需要 GLIBC_2.29 才能运行——这条约束同时写进了「不兼容性变更」和「变更」小节，是日志把底层构建细节转化为用户可感知的兼容性声明的典型例子。类似地，2.1.0 曾把预构建模块所需 glibc 版本降到 2.28 以修复旧版 Linux arm64 无法启动的问题，2.2.2 则针对低版本 Linux amd64 改用内置预编译二进制解决 glibc 要求过高的启动失败。从日志可以推断，该项目长期在「Electron 新版本」与「低版本 Linux/旧系统兼容」之间做折中，并倾向于用预编译二进制来兜底。

不兼容性变更的写法：把破坏性改动说清楚

「不兼容性变更」小节是这个项目的兼容性承诺清单，历次重大调整都有完整交代：

v2.0.0 数据迁移与备份方向性（2023-01-01）

• 升级时自动迁移旧版本的「我的列表」、下载设置、快捷键设置、自定义源到新的数据格式，旧数据保留，但下载列表数据不迁移；
• 备份文件单向兼容：v2.0.0 及以后导出的列表、配置不支持导入旧版本，反向导入则支持（移动端自 v0.15.0 起支持导入 PC 端 v2 备份）；
• 同步功能当时不支持与移动端 v1.0.0 之前的版本互连。

v2.4.0 同步协议（2023-09-09）

• 同步功能至少需要 PC 端 v2.4.0、移动端 v1.1.0 或同步服务 v2.0.0 才能连接使用。

v2.5.0 平台支持收缩（2023-09-28）

• 微软与 Electron 即将结束对 Windows 7/8 的支持，默认 Windows 构建不再支持这些系统，但保留了文件名带 win7 的免安装版，并明确提示该版本缺乏安全更新；
• Windows 10 2004 已删除 32 位 OEM 支持，默认 Windows 版不再提供 32 位构建；
• 调整了 linux 下 deb、rpm 包的命名格式。

v2.6.0 自定义源 API 2.0（2024-02-01，源开发者必读）

• 更新前提示：自定义源调用方式变更可能导致第三方源停止工作，必要时需回退到 v2.5.0；
• 与移动端统一后不再推荐使用 window.lx，改用 globalThis.lx（移动端无 window 对象）；
• inited 事件不再需要传递 status 属性，成功调用 inited 之前的任何首次未捕获错误即视为初始化失败；
• 新增 globalThis.lx.env（桌面端固定为 desktop）与 globalThis.lx.currentScriptInfo（可读取脚本头部注释信息与原始内容，其中 rawScript 用于获取脚本原始代码字符串）；
• globalThis.lx.version 更新到 2.0.0；自定义源不再以 script 标签形式执行；
• local 源新增 musicUrl、pic、lyric 的获取操作。

v2.6.0 内置源移除

• 日志明确写明：因收到腾讯投诉要求停止提供内置的连接至其平台的在线播放及下载服务，自 2023-10-18 起移除所有内置源。这是理解当前版本功能边界的关键一条——当前仓库 src/renderer/utils/musicSdk 中保留的源能力需结合自定义源机制来使用。

这种写法（变更原因 + 受影响范围 + 回退/迁移建议）是解读该项目任意版本升级风险时最可靠的一手资料。

启动参数的日志演进与源码印证

更新日志中多次以「新增启动参数」的形式扩充命令行能力，各参数的引入版本依次为：

参数	引入版本	作用
-nt	0.14.0	非透明模式启动（Windows 7 不强制开启透明效果）
-dha	1.6.0	禁用硬件加速启动；-nt 于同版更名为 -dt（旧名保留过渡）
-search="..."	0.17.0	启动时自动搜索指定内容，例：.\lx-music-desktop.exe -search="突然的自我 - 伍佰"
-dhmkh	1.9.0	禁用 Chromium 的 Hardware Media Key Handling，解决漫步者部分型号耳机意外关机冲突
-play	1.8.0	启动时播放指定歌单
-proxy-server / -proxy-bypass-list	1.17.0	代理应用所有流量；绕过列表以分号分隔，与 -proxy-server 一起使用才有效
-hidden	2.12.0	启动时最小化到系统托盘

这些参数在源码中的契约定义位于 src/common/types/common.d.ts 的 LX.CmdParams 接口，注释与日志条目一一对应，其中还补充了日志里没有的操作语义：-proxy-server 示例为 -proxy-server="127.0.0.1:1081"，且「应用内 设置→网络→代理设置 仅代理接口请求的流量，优先级更高」，-proxy-bypass-list 示例为 "<local>;*.google.com;*foo.com;1.2.3.4:5678"。

实现侧的处理入口在 src/main/app.ts 的 applyElectronEnvParams()：

export const applyElectronEnvParams = () => {
  // Is disable hardware acceleration
  if (global.envParams.cmdParams.dha) app.disableHardwareAcceleration()
  if (global.envParams.cmdParams.dhmkh) app.commandLine.appendSwitch('disable-features', 'HardwareMediaKeyHandling')
  // ...
  // proxy
  if (global.envParams.cmdParams['proxy-server']) {
    app.commandLine.appendSwitch('proxy-server', global.envParams.cmdParams['proxy-server'])
    app.commandLine.appendSwitch('proxy-bypass-list', global.envParams.cmdParams['proxy-bypass-list'] ?? '<local>')
  }
}

可以看到 -dha、-dhmkh、-proxy-server 分别映射为 Electron 的 disableHardwareAcceleration()、disable-features 开关和 proxy-server 开关；当只传 -proxy-server 时，绕过列表默认取 <local>，与 1.17.0 日志中「与 -proxy-server 一起使用才有效」的说明一致。而 2.12.0 新增的 -hidden 生效点在 src/main/modules/winMain/main.ts：ready-to-show 时若 cmdParams.hidden 为真则不 showWindow()，只保留托盘入口；src/main/app.ts 的 second-instance 场景中也做了同样的判断。

另外两条与启动参数相关的日志细节值得注意：1.9.0 修复了「配置了 http_proxy 环境变量时意外使用该代理」的问题；2.9.0 变更则明确「若设置或启动参数配置了代理，应用内的图片、音频加载与歌曲下载也走代理」，而 2.12.0 又把规则改回「不启用代理时，图片、音频加载不再走系统代理」。这条规则的两次反转正是日志中「变更」小节记录行为调整的典型样本。

更新日志的自动化生成：publish 流水线

CHANGELOG.md 并非纯手工维护，仓库内置了一套发布流水线，由 package.json 中的 "publish": "node publish" 触发，入口是 publish/index.js。其执行序列为：

1. 读取待发布内容：publish/utils/updateChangeLog.js 的默认导出读取 publish/changeLog.md（本次版本的手写变更说明）作为新条目正文；
2. 解析既有版本号：调用 publish/utils/parseChangelog.js 逐行扫描 CHANGELOG.md，用正则 ^\s*##\s+\[?(\d+\.\d+\.\d+)\]?.*?-\s+(\d{4}-\d{2}-\d{2})$ 匹配版本头，返回 [{ version, date, desc }] 列表，取第一个元素作为「上一版本」；若解析不到版本则抛出 CHANGELOG 无法解析到版本号 并终止。这也解释了为什么每个版本标题必须严格保持 ## x.y.z - YYYY-MM-DD 的形态——格式一旦破坏，发布脚本就无法工作；
3. 拼接新条目：新条目标题由上一版本与新版本自动生成 compare 链接（/compare/v{prev}...v{new}），日期取自 formatTime()，然后以正则替换 /(## \[(?:\d+\.))/ 的方式插到既有日志最上方；
4. 同步版本元数据：新版本号写入 package.json 的 version 字段与 publish/version.json，同时把旧版本描述压入 version.history 数组，version.desc 取自新 changeLog 去除标题标记后的正文；
5. 失败回滚：publish/index.js 的 catch 分支会把步骤 4 之前备份的 pkg_bak、version_bak 原样写回 package.json 和 publish/version.json，保证发布失败时仓库的版本元数据不脏污。

从源码结构看，这套流水线把「写 changeLog.md → 运行 publish → 提交 CHANGELOG.md 与版本号变更」作为标准发布节奏，与日志中每个版本头部都带有规范 compare 链接的事实相互印证。对于维护者，约束很明确：新条目的正文写在 publish/changeLog.md，不要直接手工改动 CHANGELOG.md 的既有版本头格式。

应用内如何消费更新日志

日志不只是给仓库读者的，应用本身也会消费版本信息：

• 更新日志弹窗：2.1.0 新增「当前版本更新日志显示弹窗」，更新版本后自动弹出，并新增「是否在更新版本的首次启动时显示更新日志弹窗」设置（默认开启，可在 设置→软件更新 更改）；2.1.2 专门修复了「处于最新版本时更新弹窗日志内容显示异常」「更新到最新版本后首次启动更新日志未显示」两个弹窗缺陷。对应渲染层实现可参考 src/renderer/components/layout/ChangeLogModal.vue 与 src/renderer/core/useApp/useUpdate.ts；
• 版本信息展示：2.7.0 起「设置→版本更新」中显示当前版本对应的代码提交版本与提交时间，便于用户核对构建来源；2.4.1 还借此声明「原始发布渠道只有 GitHub 及蓝奏网盘，其他渠道均为第三方转载」，是防假冒发布的官方口径；
• 自动更新：0.18.2 修复了开启托盘时无法自动更新的问题，0.11.0 优化了更新弹窗机制使自动更新版本可见下载进度，1.17.0 又为更新失败弹窗增加了「忽略提醒」按钮（同一版本再失败不再弹窗，但仍可手动查看）。

2.1.0 的日志中还有一句产品理念值得引用：「软件内功能在设计时只考虑简单便捷性，功能的新增、变更会在更新日志中注明，不会在软件内做指引提示，因此建议使用新版本时阅读一遍更新日志」——这正是该项目把 CHANGELOG.md 当作一等文档来维护的原因。

结语：如何把更新日志当作开发手册

对使用者，CHANGELOG.md 是排查「某个行为从哪个版本开始改变」的第一入口：换源机制、随机播放与已播放队列、同步连接要求、歌词罗马音/翻译展示顺序（2.12.0 起默认调换，可经设置恢复）等行为的默认值变更都记录在案。对自定义源开发者，2.6.0 的「不兼容变更」小节是 API 2.0 迁移清单；对集成方，2.8.0 的「开放API变更」小节给出了 /status 与 /subscribe-player-status 字段对齐、filter 参数与 lyricLineAllText 字段等契约变化。而发布侧的 publish 流水线则展示了「版本头格式即解析契约」的工程细节——维护日志格式，就是维护发布工具链。