Catime 的 Chocolatey 打包与发布实战:从本地构建、校验到社区仓库自动化发布
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 的逻辑非常直白,共三步:
- 静默终止旧进程:
Get-Process -Name 'catime' -ErrorAction SilentlyContinue找到正在运行的 Catime 后Stop-Process -Force,避免安装时文件被占用; - 下载并校验:
Get-ChocolateyWebFile将 GitHub Releases 上的catime_<版本>.exe下载到tools目录,并传入-Checksum与-ChecksumType 'sha256',校验不通过则安装失败——这是 Chocolatey 包防篡改的第一道防线; - 创建快捷方式:
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。其处理顺序(按优先级从高到低)为:
- 多字符快捷命令:
pr(暂停/继续)、q1/q2/q3(三个快速倒计时槽位); - 单字符命令:
s(显示时间)、u(正计时)、p(番茄钟)、r(重启计时)、h(CLI 帮助对话框)、e(编辑模式)、v(切换可见性); - 番茄钟索引:
p1、p2…… 直接触发对应编号的番茄钟; - 时间表达式(兜底):
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 正是为审核员准备的核验凭据,内容包含:
- 声明安装器下载的是官方 Release 可执行文件;
- 期望的 SHA256 校验和(如 1.5.0 对应的
f89c30c2d076d22870eceee79672d9ed0f5742f994c624a9bb1a7dd61bea1e8d); - 手动核验命令:
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 发布流程可归纳为:
- 准备:确定新版本号与对应 exe 的 SHA256;
- 注入:运行
update-package.ps1 -Version <版本> -Checksum <sha256>,同步更新 nuspec、安装脚本与 VERIFICATION.txt; - 构建:
choco pack生成.nupkg到指定输出目录; - 回测:
choco install --source <本地目录> --version <版本> --yes --force→catime 25m验证 →choco uninstall; - 发布:手动触发或稳定 tag 自动触发工作流,
CHOCOLATEY_API_KEY仅用于最终choco push。
整个方案的核心原则始终一致:程序与用户数据分离——升级、卸载都只动程序本体与快捷方式,%LOCALAPPDATA%\Catime 中的配置与资源由 卸载脚本 明确"刻意保留"。对想要维护或 fork 此打包方案的开发者而言,update-package.ps1 的严格参数校验与"恰好一次替换"机制,以及 VERIFICATION.txt 的自动生成策略,都是值得直接复用的工程细节。