Catime 的 Chocolatey 打包与发布实战:从本地构建、校验到社区仓库自动化发布

原创2026-10-14 13:47:271,357 阅读
文章标签:桌面应用

Catime 的 Chocolatey 打包与发布实战:从本地构建、校验到社区仓库自动化发布

本指南以 Catime 仓库中的 Chocolatey 打包目录 为骨架,完整讲解 catime 包如何通过 Chocolatey 社区仓库分发:包括 nuspec 与安装/卸载脚本的结构拆解、update-package.ps1 的版本与校验和注入机制、本地 choco pack 构建与安装回测流程,以及稳定版 tag 触发的自动化发布链路。读完你不仅能亲手构建并验证一个 Catime 的 Chocolatey 包,还能理解其"安装/升级/卸载均保留 %LOCALAPPDATA%\Catime 用户数据"的设计意图,并掌握包内校验机制(VERIFICATION.txt + SHA256)的完整脉络。

一、背景:Catime 为何选择 Chocolatey 分发

Catime 是一款用纯 C 编写的超轻量 Windows 倒计时 / 番茄钟(Pomodoro)工具,整个可执行文件约 995KB,支持命令行计时(如 catime 25m)、托盘左键快捷设置、右键配置菜单、自定义字体、托盘动画、通知音与插件。除了 GitHub Releases 与微软商店之外,项目还通过 Chocolatey 社区仓库(Community Repository)以 catime 包名发布,用户可用一句 choco install catime 完成安装与后续升级。

该打包方案的关键设计约束写在文档首段:安装与升级都会保留 %LOCALAPPDATA%\Catime 下的配置与用户资源。也就是说,choco upgrade catime 不会清空用户的自定义动画、字体与 config.ini 配置,这与卸载脚本中"刻意保留用户数据"的注释互为印证(见下文)。

二、包结构解析:packaging/chocolatey 目录里都有什么

整个打包模块位于仓库的 packaging/chocolatey 目录,共 5 个文件,职责分明:

文件 相对路径 职责
打包清单 catime.nuspec 包元数据(id、版本、描述、标签)与文件布局
构建脚本 update-package.ps1 注入版本号、下载 URL 与 SHA256 校验和
安装脚本 tools/chocolateyinstall.ps1 下载并校验 exe、结束旧进程、创建开始菜单快捷方式
卸载脚本 tools/chocolateyuninstall.ps1 结束进程、移除快捷方式、保留用户数据
审核说明 tools/VERIFICATION.txt 供 Chocolatey 审核员与社区核验包内容可信度

2.1 nuspec:包身份与元数据

catime.nuspec 采用 2015/06 命名空间,核心元数据如下:

  • <id>catime</id>:社区仓库中的包名,安装命令 choco install catime 即对应此 id;
  • <version>1.5.0</version>:当前仓库打包基线版本;
  • <authors>/<owners>:均为 vladelaina;
  • <requireLicenseAcceptance>false</requireLicenseAcceptance>:安装无需额外接受许可;
  • <summary>:ultra-lightweight Windows countdown and Pomodoro timer(超轻量 Windows 倒计时与番茄钟);
  • <description>:补充说明其能力——支持 catime 25m 命令行计时、托盘左键快捷操作、右键配置菜单、自定义字体、托盘动画、通知音与插件;
  • <tags>:catime timer countdown pomodoro clock tray portable windows,用于社区仓库的检索分类;
  • <files>:仅把 tools\** 目录内容映射为包内 tools 目录——这是 Chocolatey 包的约定布局,安装脚本必须位于 tools/chocolateyinstall.ps1。

2.2 安装脚本:下载、校验、建快捷方式

tools/chocolateyinstall.ps1 的逻辑非常直白,共三步:

  1. 静默终止旧进程:Get-Process -Name 'catime' -ErrorAction SilentlyContinue 找到正在运行的 Catime 后 Stop-Process -Force,避免安装时文件被占用;
  2. 下载并校验:Get-ChocolateyWebFile 将 GitHub Releases 上的 catime_<版本>.exe 下载到 tools 目录,并传入 -Checksum 与 -ChecksumType 'sha256',校验不通过则安装失败——这是 Chocolatey 包防篡改的第一道防线;
  3. 创建快捷方式:Install-ChocolateyShortcut 在 [Environment]::GetFolderPath('Programs')(即开始菜单 Programs 目录)生成 Catime.lnk,指向 tools\catime.exe。

2.3 卸载脚本:清理程序、保留数据

tools/chocolateyuninstall.ps1 同样先强制结束 catime 进程,再删除 Catime.lnk 快捷方式。最后一行注释点明设计意图:

# User configuration under %LOCALAPPDATA%\Catime is intentionally preserved.

卸载只移除程序本体与快捷方式,刻意保留 %LOCALAPPDATA%\Catime 下的配置与用户资源,这正是 README 第一段承诺的实现细节。

三、本地构建:update-package.ps1 的版本与校验和注入

发布流程的第一步是准备包内容。在已安装 Chocolatey 的 Windows 环境中执行:

.\packaging\chocolatey\update-package.ps1 `
  -Version 1.5.0 `
  -Checksum f89c30c2d076d22870eceee79672d9ed0f5742f994c624a9bb1a7dd61bea1e8d

3.1 参数校验规则

从 update-package.ps1 的 param 块可见两道强制校验:

  • -Version:必须匹配 ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$,即主.次.修订三段式版本号,可选 -prerelease 后缀;
  • -Checksum:必须匹配 ^[0-9a-fA-F]{64}$,即 64 位十六进制 SHA256 摘要,脚本随后会统一转小写(ToLowerInvariant)写入各文件。

3.2 脚本实际改动了什么

脚本在 $ErrorActionPreference = 'Stop' 与 Set-StrictMode -Version Latest 的严格模式下执行,对 4 处文件内容做"恰好一处"的替换(Replace-SingleMatch 会校验匹配次数必须为 1,否则抛错):

目标文件 替换内容
catime.nuspec <version> 更新为 -Version 传入值;<releaseNotes> 更新为对应 v<版本> 的 Release 页面
tools/chocolateyinstall.ps1 $url 更新为 https://github.com/vladelaina/Catime/releases/download/v<版本>/catime_<版本>.exe;$checksum 更新为小写的 SHA256
tools/VERIFICATION.txt 整体重新生成,写入下载 URL 与期望校验和,以及手动核验命令

所有写入均使用 [System.Text.UTF8Encoding]::new($false) 生成 UTF-8 无 BOM 文本,避免 PowerShell 5.1 默认编码导致的中文或特殊字符乱码问题。执行结束后控制台会打印 Prepared Chocolatey package for Catime <版本>、Release URL 与 SHA256,方便人工复核。

3.3 构建 nupkg

参数注入完成后,用 choco pack 依据 nuspec 生成可安装的 .nupkg:

choco pack .\packaging\chocolatey\catime.nuspec `
  --output-directory .\chocolatey-output

产物即位于 .\chocolatey-output 目录,供本地测试或后续 choco push 使用。

四、本地回测:安装 → 使用 → 卸载

文档给出了完整的回测闭环,全部指向本地源(--source .\chocolatey-output),不依赖社区仓库:

choco install catime --source .\chocolatey-output --version 1.5.0 --yes --force
catime 25m
choco uninstall catime --yes
  • --version 1.5.0:精确锁定刚构建的版本;
  • --yes:跳过交互确认,适合脚本化测试;
  • --force:即使本机已存在同名包也强制重装,方便反复迭代验证;
  • catime 25m:启动后直接进入 25 分钟倒计时,这是验证程序本体可运行的关键一步。

4.1 catime 25m 背后的 CLI 解析逻辑

catime 25m 并非简单传参,而是走 src/cli.c 中的 HandleCliArguments 解析链路,入口声明见 include/cli.h。其处理顺序(按优先级从高到低)为:

  1. 多字符快捷命令:pr(暂停/继续)、q1/q2/q3(三个快速倒计时槽位);
  2. 单字符命令:s(显示时间)、u(正计时)、p(番茄钟)、r(重启计时)、h(CLI 帮助对话框)、e(编辑模式)、v(切换可见性);
  3. 番茄钟索引:p1、p2…… 直接触发对应编号的番茄钟;
  4. 时间表达式(兜底):25m、1h30m、1 30(分:秒)、1 30 15(时:分:秒)、14 30t(截止时刻)等自然输入都会解析为总秒数并调用 StartCountdownWithTime 启动倒计时。

值得注意的设计:无效输入不会报错中断,而是回退到默认倒计时对话框(StartDefaultCountDown),以保持"快速工作流"的连续体验;同时,-- 开头的命令行 flag 会被显式忽略(LOG_INFO 记录后返回 FALSE)。因此测试命令 catime 25m 能稳定复现"25 分钟倒计时"这一核心场景。

五、用户数据为何保存在 %LOCALAPPDATA%\Catime

整个打包方案反复强调保留 %LOCALAPPDATA%\Catime,其原因在配置路径源码中一目了然:

  • src/config/config_path_sources.c 在 AppData\Local 根下拼接出 Catime 目录与 config.ini(_snwprintf_s(L"%s\\Catime", root)、L"%s\\Catime\\config.ini"),即用户配置落盘位置;
  • src/config/config_local_appdata.c 负责解析"有效 LocalAppData 路径":普通安装直接走 SHGetKnownFolderPath / CSIDL_LOCAL_APPDATA;若检测到正在以 Store 打包应用(Packaged App)运行,则改映射到 %USERPROFILE%\AppData\Local\Packages\<PackageFamilyName>\LocalCache\Local。该文件还实现了 %LOCALAPPDATA% 占位符的展开与旧版 Store 配置的兼容去重逻辑。

因此,无论通过 Chocolatey 安装、升级还是卸载,Catime 都把 %LOCALAPPDATA%\Catime 视为"非程序本体"的独立用户数据域——配置、动画资源、字体等资源不会随包生命周期丢失。

六、发布:从手动触发到 tag 自动发布

文档的 Publishing 一节描述了发布链路的调度方式:

  • 首次发布:Chocolatey 发布工作流需手动触发;
  • 后续发布:当仓库创建稳定版 tag(Stable tag)Release 时,同一工作流会被自动调用,即"打 tag → GitHub Release 创建 → 自动构建并发布 Chocolatey 包";
  • 密钥隔离:CHOCOLATEY_API_KEY 仓库密钥只被传递给最终的 choco push 步骤,其余构建与测试步骤不接触发布密钥,遵循最小权限原则,降低密钥泄露面。

需要注意的是,当前仓库目录中并不包含 .github/workflows 定义文件(已检索确认),因此本节内容以 packaging/chocolatey/README.md 的文档描述为准;本地构建与回测流程不受影响。

七、安全与可审计性:VERIFICATION.txt 与 SHA256

Chocolatey 社区仓库对包内容有严格审核机制,tools/VERIFICATION.txt 正是为审核员准备的核验凭据,内容包含:

  1. 声明安装器下载的是官方 Release 可执行文件;
  2. 期望的 SHA256 校验和(如 1.5.0 对应的 f89c30c2d076d22870eceee79672d9ed0f5742f994c624a9bb1a7dd61bea1e8d);
  3. 手动核验命令:
Get-FileHash .\catime_1.5.0.exe -Algorithm SHA256

由于该文件由 update-package.ps1 在每次发版时自动重新生成(而非手写维护),校验和与安装脚本中的 $checksum 始终保持一致,杜绝"文档与脚本脱节"的人为失误。

八、与仓库测试的呼应:Chocolatey 路径的识别

打包路径与程序运行时的"快捷方式修复"策略存在联动:在 tests/shortcut_policy_tests.c 中,有一条针对 Chocolatey 安装路径的用例:

"rejects unpackaged install",
ShortcutPolicy_IsLegacyPackagedTarget(
    "C:\\ProgramData\\chocolatey\\lib\\catime\\catime.exe",
    packageName, executableName), false);

该测试验证:位于 C:\ProgramData\chocolatey\lib\catime\ 下的 exe 会被正确判定为非 Store 打包安装(返回 false),从而不会触发针对微软商店虚拟化路径的快捷方式修复逻辑。这从侧面说明,Chocolatey 安装与 Store 打包安装被程序明确区分对待,两条分发渠道互不干扰。

九、小结:一条可复现的发布流水线

把文档与源码串起来,Catime 的 Chocolatey 发布流程可归纳为:

  1. 准备:确定新版本号与对应 exe 的 SHA256;
  2. 注入:运行 update-package.ps1 -Version <版本> -Checksum <sha256>,同步更新 nuspec、安装脚本与 VERIFICATION.txt;
  3. 构建:choco pack 生成 .nupkg 到指定输出目录;
  4. 回测:choco install --source <本地目录> --version <版本> --yes --force → catime 25m 验证 → choco uninstall;
  5. 发布:手动触发或稳定 tag 自动触发工作流,CHOCOLATEY_API_KEY 仅用于最终 choco push。

整个方案的核心原则始终一致:程序与用户数据分离——升级、卸载都只动程序本体与快捷方式,%LOCALAPPDATA%\Catime 中的配置与资源由 卸载脚本 明确"刻意保留"。对想要维护或 fork 此打包方案的开发者而言,update-package.ps1 的严格参数校验与"恰好一次替换"机制,以及 VERIFICATION.txt 的自动生成策略,都是值得直接复用的工程细节。

登录后查看全文
Catime