BongoCat三平台打包与发布指南：Windows安装程序、Microsoft Store与Linux AppImage详解-平芜编程栈

BongoCat三平台打包与发布指南：Windows安装程序、Microsoft Store与Linux AppImage详解

【免费下载链接】BongoCat🩷 💘C × SDL3 × OpenGL — Three Mysterious Forces, United as One! Bong~ Bongocat!!!Don't be shy, Join Here🧸: https://discord.gg/vf8jqnattk项目地址: https://gitcode.com/gh_mirrors/bongo/BongoCat

BongoCat（敲键盘小猫）是一款基于 C × SDL3 × OpenGL 的 Live2D 桌面宠物，会跟随你的键盘和鼠标输入做出敲击动作。本文带你完整看懂 BongoCat 的打包与发布体系：Windows 安装程序（Inno Setup 生成 setup.exe）、Microsoft Store 应用包（MSIX）、Linux AppImage，以及便携版和版本命名规则，帮你从源码一键产出可发布的安装包。

1️⃣ 打包体系总览：CMake 如何统一管理三个平台

BongoCat 的发布逻辑全部由 CMake 驱动，核心入口是 cmake/Packaging.cmake，它在安装目标（install(TARGETS bongo_cat ...)）之后依次挂载各平台的打包逻辑：

平台	打包方式	产物格式	对应文件
Windows	CPack ZIP + Inno Setup	`setup.exe`安装程序 + ZIP + 便携 exe	cmake/PackagingInno.cmake
Microsoft Store	MSIX 封装脚本	`bongocat_x.x.x_x64.msix`	packaging/microsoft-store/
Linux	linuxdeploy + AppImage	`BongoCat-x.x.x-linux-x64.AppImage`	cmake/PackagingAppImage.cmake

几个值得新手注意的细节：

架构探测：cmake/PackagingPlatform.cmake 会根据指针宽度自动判定x64/x86，并生成平台标签（如windows-x64、linux-x64）。
包名规则：最终产物统一命名为BongoCat-版本号-平台，例如BongoCat-1.14.0-windows-x64-setup.exe，命名写入build/bongocat-package-name.txt供脚本校验（见 cmake/Packaging.cmake）。
诊断后端：若未提供 Cubism SDK，产品名会变为BongoCat-Diagnostic并附带 cmake/DiagnosticBuildNotice.txt，避免把诊断版误当成完整版发布。
校验和：CPack 默认生成 SHA256 校验文件，配合CPACK_INSTALL_CMAKE_PROJECTS只打包 Runtime 组件，保证安装目录里只有运行所需文件。

2️⃣ Windows 安装程序：用 Inno Setup 产出 setup.exe

Windows 是发布渠道最多的平台：安装版、便携版、Store 版并存。

一键构建安装程序

完成常规构建后，执行package-installer目标即可生成安装程序。cmake/PackagingInno.cmake 会先渲染三个.iss.in模板，再调用 packaging/windows/build-installer.ps1 自动查找并运行 Inno Setup 编译器ISCC：

cmake --build build --config Release --target package-installer

脚本内含完善的错误处理：捕获 ISCC 退出码、把完整日志写入build/installer.log，失败时抛出具体的ResourcePreparationFailed异常，方便定位打包问题。

安装脚本做了什么

主模板 packaging/windows/BongoCat.iss.in 的关键配置：

PrivilegesRequired=lowest：用户级安装，无需管理员权限；
CloseApplications=yes：安装前自动检测并关闭正在运行的BongoCat.exe；
桌面快捷方式带--nearby-root参数，让 BongoCat 可以扫描桌面附近的模型包；
ArchitecturesAllowed=x64compatible：64 位版只允许装在 64 位系统。

两个辅助模板处理安装生命周期：

packaging/windows/install-lifecycle.iss.in：探测旧版本安装目录，处理升级迁移与版本比较；
packaging/windows/uninstall-autostart.iss.in：卸载时清理开机自启动项。

便携版：单文件 exe

除了安装程序，cmake/Packaging.cmake 还提供package-portable目标，直接把BongoCat.exe复制为BongoCat-x.x.x-windows-x64-portable.exe，双击即用、无安装残留，非常适合内网分发。

3️⃣ Microsoft Store 版：MSIX 打包与数据隔离

想上架 Microsoft Store 的应用必须使用 MSIX 封装。BongoCat 的 Store 包只针对 x64，详细文档见 packaging/microsoft-store/README.md。

应用清单：AppxManifest

packaging/microsoft-store/AppxManifest.xml.in 定义了包身份与能力：

包名vladelaina.bongocat，声明runFullTrust能力（桌面宠物需要读取全局输入，必须全信任模式）；
通过desktop7:windows.shortcut扩展声明桌面快捷方式，由 Windows 在装/卸包时自动管理；
Resources节点一次性声明了 11 种语言（含zh-cn、zh-hant），与 docs/ 目录下的多语言 README 一一对应。

版本号的小陷阱

MSIX 要求版本号是四段式数字且修订位为 0。packaging/get-project-version.ps1 会自动把项目版本1.14.0转成1.14.0.0，版本号唯一来源是顶层 CMakeLists.txt 中的BONGO_CAT_VERSION，改动一处即可同步所有脚本。

本地构建与验证流程

cmake -S . -B build-cubism -G "Visual Studio 17 2022" -A x64 -DBONGO_CAT_REQUIRE_CUBISM=ON cmake --build build-cubism --config Release --target bongo_cat --parallel 2 .\packaging\microsoft-store\build-store-package.ps1 -ExecutablePath .\build-cubism\Release\BongoCat.exe

产出的未签名MSIX 需上传到 Partner Center 由微软签名后才能安装。本地可先做两件事验证：

用 packaging/microsoft-store/validate-store-package.ps1 检查身份、PFN、清单与可执行文件版本、架构及"未签名待提交"状态；
如需本地侧载测试，加-SignForLocalTesting参数生成自签名包，导入证书后Add-AppxPackage安装（该证书仅限测试，切勿上传商店）。

桌面版与 Store 版的数据隔离

一个容易被忽略的细节：当进程带有 MSIX 包身份时，BongoCat 会把数据目录切到包私有虚拟化路径%LOCALAPPDATA%\Packages\<PFN>\LocalCache\Local\BongoCat，而桌面版使用%LOCALAPPDATA%\BongoCat。两个版本的配置、导入模型、缓存和日志完全隔离，同一台电脑可以共存互不干扰。

4️⃣ Linux AppImage：一条命令生成免安装文件

Linux 渠道由 cmake/PackagingAppImage.cmake 在linux-x64平台下注册package-appimage目标，实际工作交给 packaging/linux/build-appimage.sh：

# 依赖安装（Debian/Ubuntu 示例） sudo apt-get install -y build-essential cmake ninja-build \ libgl1-mesa-dev libx11-dev libxi-dev libxfixes-dev libfontconfig1-dev fonts-noto-cjk cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DBONGO_CAT_FETCH_DEPS=ON cmake --build build --parallel cmake --build build --target package-appimage

脚本内部流程值得学习：

校验bongocat-package-name.txt必须符合BongoCat(-Diagnostic)?-x.y.z-linux-x64格式，防止误打包诊断版；
用cmake --install --component Runtime在临时目录搭建AppDir，保持资产与可执行文件同目录（运行时依赖这一布局）；
下载固定版本的linuxdeploy-x86_64.AppImage工具，注入 packaging/linux/bongocat.desktop 桌面条目与图标；
输出dist/BongoCat-x.x.x-linux-x64.AppImage并自动生成.sha256校验文件。

得益于 cmake/PlatformRuntime.cmake 与linuxdeploy的 bundle 机制，产出的 AppImage 自带 GL/X11 运行时，在较新的主流发行版上双击即可运行。

5️⃣ 发布清单与版本管理速查

发布前建议对照检查：

✅ 版本一致性：CMakeLists.txt的BONGO_CAT_VERSION与产物文件名、MSIXIdentity.Version三者一致；
✅ 完整性：确认产物是正式版而非BongoCat-Diagnostic（无 Cubism SDK 时的诊断后端）；
✅ 校验和：每个产物都附带 SHA256（CPack 与 AppImage 脚本均自动生成）；
✅ 测试通过：构建后运行ctest --test-dir build --output-on-failure，项目默认启用 cmake/Tests.cmake 中的 CTest 用例；
✅ 许可证文件随包分发：Windows 版会一并安装 LICENSE 与模型目录的 MIT 许可声明。

产物	目标命令	适用场景
`…-setup.exe`	`--target package-installer`	Windows 用户级安装、带升级迁移
`…-portable.exe`	`--target package-portable`	免安装、U盘分发
`bongocat_x.x.x_x64.msix`	`build-store-package.ps1`	Microsoft Store 上架
`…linux-x64.AppImage`	`--target package-appimage`	Linux 免安装分发
ZIP / TGZ 归档	CPack（`cmake --build build --target package`）	裸包、CI 备用渠道

写在最后

BongoCat 的发布体系展示了原生 C/C++ 项目多平台分发的完整思路：用 CMake 统一"构建—安装—打包"三段式，Inno Setup 负责 Windows 安装体验，MSIX 对接商店生态，AppImage 覆盖 Linux 用户，同时靠命名规则、诊断版标记和 SHA256 校验守住发布质量底线。掌握这套流程后，你完全可以把它迁移到自己 C/SDL/OpenGL 项目的 CI 流水线中。

如果本文对你有帮助，欢迎按Ctrl + D收藏本仓库，参与 BongoCat 社区讨论一起打磨这只敲键盘的小猫 🐱

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考