Qt 桌面项目脚手架

它解决什么

不是教你写 Qt，而是把「项目外围那圈东西」一次搭好。它们单个都不难，凑在一起最耗时间，而且每个项目都会漏一点：

• 版本号散落。CMake、rc 文件、安装包名、tag 各写一份，发版前总要找一遍。
• 构建脚本靠记忆。Qt 路径、VS 环境、Ninja、windeployqt、要删哪些 DLL，换台机器就重来。
• 更新程序从零写。检查版本、下载、验签、替换、保留配置，每一步都能出错。
• 关于页永远是最后补的。版本、Qt 版本、开源许可、项目链接，临时拼一段文本。

脚手架把这些收进模板和脚本，新项目从第一天就带着它们。

一条命令生成

python "$KIT/tools/new_project.py" --dest D:\Dev\DemoApp `
  --name DemoApp --display "示例应用" `
  --gitee owner/repo --with-updater

加 --dry-run 只预演；目标目录非空时默认拒绝。

生成的是完整可编译工程，不是目录占位：

DemoApp/
├── CMakeLists.txt              版本、Qt、rc 资源、主程序与 Updater
├── VERSION                     版本号唯一真源
├── build-release.bat           探测 Qt/VS/CMake，编译并部署到 run\
├── cmake/GenerateVersionRC.cmake
├── resources/app.rc.in         版本资源模板
├── src/
│   ├── main.cpp                单实例、--version、--selftest、--quit
│   ├── MainWindow.*            最小窗口 + 帮助菜单
│   ├── AboutDialog.*           关于 / 开源许可
│   └── Update*.*               可选更新模块
└── tools/                      版本、构建、打包、签名、发布脚本

占位符统一替换项目名、显示名、作者、邮箱、Gitee 仓库和年份；生成后不会残留 {{。

版本号只有一份

根目录 VERSION 写 x.y.z，CMake、编译宏、rc 资源、Git tag、发布包名、版本说明全部从它派生。升级只跑：

pwsh -NoProfile -File tools\bump-version.ps1 minor
# 填写 tools\release-notes\vX.Y.Z.md 后提交

更实用的是 rc 资源：构建时自动取 Git commit 短 id，工作区有未提交改动就加 M，写进 exe 属性。测试项目实测结果：

PrivateBuild     "2aa1b2e"
ProductVersion   "0.1.0+2aa1b2e"
Comments         "Git 提交 2aa1b2e"

改过代码没提交时显示 2aa1b2eM，一眼能看出这个包不是干净构建。

再加一层版本守卫：tag 已经打过的版本号不允许继续提交；普通分支发版必须升 MINOR，只修 bug 走 hotfix/* 分支升 PATCH；VERSION 合并冲突由 merge driver 自动取较高版本。

构建、打包、签名

build-release.bat 自动探测 Qt（6.5/6.8 常见路径，支持 QT_DIR）、VS 2022/2026、CMake 与 Ninja，编译后部署到 run\：

• windeployqt 只带需要的 Qt 库，再删掉 Network/Pdf/Svg、dxcompiler/dxil 等用不到的文件。
• 就地覆盖，不删除 run\，不覆盖用户配置；构建前只停当前项目自己的实例。
• CRT 随包，目标机器不需要额外装 VC++ 运行库。

发布包由 package-release.ps1 生成：剔除日志、自检报告、本机配置，zip 顶层带版本目录，再用 RSA-3072 / SHA-256 生成 .zip.sig。同一版本重复打包时，还会和上一版做文件级 diff，生成只含变化文件的增量包。

实测产物：10.7 MB 完整包 + 384 字节签名；包里没有 keys、config、日志。

更新程序不是伪代码

--with-updater 会把更新链路一起装进项目：

• 检查：后台线程请求 Gitee 最新发行版，解析完整包、增量包与签名地址。
• 下载：WinHTTP 下载，自动代理失败回退直连，带进度与取消。
• 验签：BCrypt 校验 RSA-3072 签名，不通过不落盘。
• 替换：独立 Updater 等主程序退出，覆盖文件、删除旧文件、保留配置，再重启。

签名密钥用 generate-update-key.ps1 生成，私钥只留在本机或私有仓库；仓库转公开前可以一键轮换。发布脚本 release.ps1 串起编译、自检、打包、签名、Gitee 发版和源码 tag，任何一步失败就停。

已经用演示仓库跑通一次真实升级：v0.1.0 检查到 v0.2.0，下载完整包、验签、替换并重启，升级后 --version 返回 ScaffoldDemo 0.2.0，日志与换肤菜单同时生效。

关于页也一起给了

生成的项目自带三个入口，不用再临时拼：

• 关于

  应用名、标语、版本、Qt 版本、位数、项目主页、作者与邮箱。

• 关于 Qt

  直接调用 QApplication::aboutQt，不自己抄一份。

• 开源许可

  Qt LGPL-3.0 动态链接，以及 PCRE2、zlib、libpng、FreeType、HarfBuzz 的许可与链接。

显示信息由 CMake 编译宏注入，改一处即可，不会在多个 cpp 里出现不同版本。

小试记录

不是只跑静态检查，实际生成并编译了一遍：

• 生成：47 个文件，更新模块与密钥一起就位，无残留占位符。
• 构建：Qt 6.8.3 + VS 2026 + Ninja，主程序与 Updater 均链接成功。
• 运行：--version 返回 DemoApp 0.1.0；--selftest 退出 0，报告无 [FAIL]。
• 打包：zip + .sig 生成，增量包逻辑在无历史版本时正确跳过。
• 升级：演示仓库 v0.1.0 → v0.2.0 完整升级成功，升级后版本、日志、换肤菜单均生效。
• 版本守卫：打 tag 后只升 PATCH 的提交被拦下，提示升 MINOR 或切 hotfix。
• 安装：skill 安装脚本 61 个文件原子落盘，OpenCode 能发现。

边界与现状

• 只面向 Windows 桌面：脚本假设 MSVC、windeployqt、WinHTTP；Qt Quick、移动端、嵌入式不适用。
• 更新只在演示仓库验证过：v0.1.0 → v0.2.0 已跑通完整流程；更多网络环境与旧系统还需实际使用观察。
• v0.1.0：模板接口还会随使用调整；生成后的项目可以独立演进，不必跟着 skill 升级。
• 不适合：一次性脚本、已有成熟发布体系的项目，或者只需要一个单文件 demo 的场景。