Lapce 新版本发布指南：版本号的 6 处包元数据同步点与打包流程解析

Lapce 的发布流程要求版本号在多个异构元数据文件（AppStream、Info.plist、Cargo、RPM spec、WiX 等）中保持严格一致，漏改任何一处都会导致包管理器元数据与实际二进制版本不符。本文基于 docs/new-release.md 的官方清单，逐处解析这 6 个版本的落点、格式约束与底层打包链路，帮助你在发布新版本时完成一次完整、可验证的版本同步。

为什么一次发布要动 6 处版本信息

Lapce 是一个 Cargo workspace 项目，但分发给用户的产物横跨三种平台、多种包格式：Linux 的 AppImage/静态二进制与 AppStream 元数据、macOS 的 .app/DMG、Windows 的 WiX 安装包，以及用于 RPM 打包的 spec 文件。每个分发渠道都有自己的版本字段，Cargo 的版本号只会流入 Rust 侧的 --version 等输出，不会自动传播到 Info.plist、WiX 或 AppStream 文件。因此官方文档 docs/new-release.md 列出的清单本质上是一张"发布前必须同步修改的文件表"：

#	版本落点	文件	格式特征
1	App metainfo（AppStream）	extra/linux/dev.lapce.lapce.metainfo.xml	<release version="X.X.X" date="...">
2	macOS plist（CFBundleShortVersionString）	extra/macos/Lapce.app/Contents/Info.plist	plist 字符串键值
3	Rust workspace	Cargo.toml	version = "X.X.X"（workspace 共享）
4	变更日志	CHANGELOG.md	Markdown 分节
5	RPM spec	lapce.spec	Version: X.X.X.{{{ git_dir_version }}}
6	Windows WiX（<Product ... Version=X.X.X>）	extra/windows/wix/lapce.wxs	Product 属性

当前仓库中这 6 处均一致指向 0.4.6，可作为一次完整同步的参照基线。

1. Rust 侧：Cargo workspace 统一版本

Rust 版本号的唯一权威位置是根 Cargo.toml 的 [workspace.package] 段：

[workspace.package]
version      = "0.4.6"
edition      = "2024"
rust-version = "1.87.0"
license      = "Apache-2.0"
homepage     = "https://lapce.dev"
authors      = ["Dongdong Zhou <[e-mail]>"]

子 crate 不再各自写版本号，而是通过 version = { workspace = true } 继承（见 lapce-app/Cargo.toml）。这意味着只需修改根 Cargo.toml 一处，lapce、lapce-app、lapce-proxy 等所有工作区成员的版本即同步变更，避免 crate 间版本漂移。

版本号同时是打包链路的输入：RPM spec 的构建命令为 cargo build --profile release-lto --package lapce-app --frozen（lapce.spec），Windows WiX 包的文件源是 .\target\release-lto\lapce.exe（lapce.wxs），即发布产物固定走 release-lto profile（该 profile 在 Cargo.toml 中启用 LTO 并将 codegen-units 设为 1）。

2. AppStream metainfo：Linux 应用中心的版本与发布记录

extra/linux/dev.lapce.lapce.metainfo.xml 是 AppStream 元数据（组件 id 为 dev.lapce.lapce），它决定 GNOME Software、KDE Discover 等应用中心显示的应用摘要、分类与更新历史。发布新版本时需要在 <releases> 段头部追加一条记录，当前形态为：

<releases>
    <release version="0.4.6" date="2026-01-21">
        <url type="details">https://github.com/lapce/lapce/releases/tag/v0.4.6</url>
        <issues>
            <issue url="https://github.com/lapce/lapce/issues/3821">#3821</issue>
            ...
        </issues>
    </release>
    <release version="0.4.5" date="2025-09-05">...</release>
</releases>

每条 <release> 包含版本号、日期、release 详情页链接和本次修复的 issue 列表。注意这个文件会被安装进系统：spec 的 %install 段将其装到 /usr/share/metainfo/dev.lapce.lapce.metainfo.xml（lapce.spec），所以 metainfo 的版本记录就是 Linux 用户看到的"更新日志"，漏写条目等同于该版本在应用中心"无声无息"。

3. macOS：Info.plist 的两个版本键

extra/macos/Lapce.app/Contents/Info.plist 是 Lapce.app 模板的一部分，关键版本字段是 CFBundleShortVersionString（面向用户的营销版本号，当前为 0.4.6，见 Info.plist）与 CFBundleVersion（构建号，当前为 1，通常不需要随小版本变化）。

源码可以确认这个模板的实际用途：Makefile 中 APP_TEMPLATE = extra/Lapce.app，构建 Lapce.app 目标时会把整个模板 cp -fRp 到 target/release-lto/macos/，再把编译出的二进制放进 Contents/MacOS。也就是说 Info.plist 的版本号不会被任何构建脚本自动改写，必须手工同步。后续签名与 DMG 打包（codesign、hdiutil）都在此模板之上进行（Makefile）。

这里有一条真实教训：CHANGELOG.md 0.4.5 节明确记录了 "Fix incorrect version in macOS/Windows package metadata" 这一修复项——即历史上确实出现过 plist/WiX 版本号落后于实际发布的事故，这正是本清单存在的原因。

4. Windows：WiX Product 的 Version 属性

Windows 安装包由 extra/windows/wix/lapce.wxs 定义，版本号位于 <Product> 元素的 Version 属性：

<Product Name="Lapce" Id="*" UpgradeCode="9c09a374-1135-4782-959f-2dec376a1dfa"
         Language="1033" Codepage="1252" Version="0.4.6" Manufacturer="Lapce">

有两点值得注意：

• WiX 要求三段式版本号（X.Y.Z），不支持四段；而 UpgradeCode 必须保持不变，否则 Windows 无法识别为同产品的升级，旧版本不会被正确替换（文件中 MajorUpgrade AllowSameVersionUpgrades="yes" 即依赖这一点）。
• 该安装器还会把 [LapceProgramFiles] 写入 PATH、注册"Open Lapce here"目录右键菜单（lapce.wxs），这些组件的升级判定同样以 Product 版本号为依据。

5. RPM spec：gitdir 占位符与四段版本号

lapce.spec 采用 gitdir 风格的模板占位符：

Name:           lapce-git
Version:        0.4.6.{{{ git_dir_version }}}
Release:        1
...
VCS:            {{{ git_dir_vcs }}}
Source:         {{{ git_dir_pack }}}

其中 {{{ git_dir_version }}}、{{{ git_dir_vcs }}}、{{{ git_dir_pack }}} 是打包工具（如 copack/gitdir 类打包器）在运行时从 git 仓库注入的占位符，最终版本形如 0.4.6.<提交号> 的四段式。因此手工维护的部分只有前缀 0.4.6，发布时把它改成新版本即可，后缀交给工具链生成。构建依赖（vulkan、wayland、libxcb 等开发库）在 BuildRequires 中声明，构建过程先 cargo fetch --locked 再走 release-lto profile（lapce.spec）。

6. CHANGELOG.md：Unreleased 分节约定

CHANGELOG.md 遵循 Keep-a-Changelog 风格的结构：顶部是 ## Unreleased 分节（含空的 Features/Changes 与 Bug Fixes 两小节），其下按 0.4.6、0.4.5… 逐版本排列。日常工作流是：开发期间把条目先写进 Unreleased，发布时把该节重命名为新版本号并补一条空的 Unreleased 骨架。以 0.4.6 为例（CHANGELOG.md），条目分"功能/变更"与"Bug 修复"两类，并附对应的 issue/PR 编号——这些编号也正是 metainfo 里 <issue> 列表的来源，两处内容应当相互对应。

发布操作清单与验证

综合以上 6 处，一次版本发布（如 0.4.6 → 0.4.7）的完整操作为：

1. 修改 Cargo.toml 的 [workspace.package] version；
2. 在 CHANGELOG.md 中把 Unreleased 重命名为 0.4.7 并补空骨架；
3. 在 metainfo.xml 的 <releases> 头部追加 <release version="0.4.7" date="..."> 及 issue 列表；
4. 更新 Info.plist 的 CFBundleShortVersionString；
5. 更新 lapce.spec 的 Version 前缀；
6. 更新 lapce.wxs 的 <Product ... Version="0.4.7">。

验证方式很简单——在仓库内搜索旧版本号，6 个文件（外加 Cargo.lock）应当全部命中新版本号，即上面清单恰好对应 0.4.6 的全部文件命中集合。

版本号之外：打包链路与 nightly 分支

改完版本号后，产物如何生成？Linux 侧由 docker-bake.hcl 驱动的 docker buildx 矩阵完成：它按发行版（debian bookworm/bullseye、ubuntu 多版本、fedora 39–43/rawhide、alpine 静态二进制）展开 target，静态链接参数（OPENSSL_STATIC、LIBGIT2_STATIC 等）区分 binary（静态）与 package（动态）两条产物线，各发行版的构建环境定义在 extra/linux/docker/ 下的 Dockerfile 中。该文件还区分了正式与夜构建：PACKAGE_NAME 在 RELEASE_TAG_NAME == "nightly" 时为 lapce-nightly，否则为 lapce（docker-bake.hcl）——nightly 通道复用同一套版本号体系，不需要单独的版本文件。macOS 侧则由 Makefile 负责：binary-universal（x86_64 + aarch64 双架构 lipo 合并）、app（套用 extra/macos 模板并 codesign 签名）、dmg（hdiutil 打包）三条目标，均依赖 Keychain 中已配置的开发者签名身份（Makefile）。

小结

Lapce 的发布版本同步是一个"一改六验"的机械流程：Rust 侧由 Cargo workspace 收敛为单点，其余五个渠道（AppStream、plist、spec、WiX、CHANGELOG）则必须逐一手工对齐，且各自的格式约束不同——WiX 只收三段式、spec 需要保留 gitdir 占位符、metainfo 需要版本+日期+issue 三元组。只要按清单顺序修改并全库检索版本号做终检，就能保证用户在任何分发渠道看到的版本、更新记录与实际二进制完全一致。