如何从零构建BetterCmdTab并参与开源贡献?xcodebuild、Swift Testing与发布签名完整指南
如何从零构建BetterCmdTab并参与开源贡献?xcodebuild、Swift Testing与发布签名完整指南
BetterCmdTab 是一个完全开源的 macOS ⌘Tab 应用切换器项目。这篇指南带你用 xcodebuild 从零完成项目构建、Swift Testing 单元测试运行与发布签名,并覆盖开源贡献的关键步骤。全程命令行驱动,无需图形界面操作。
🧭 先认识 BetterCmdTab:轻量的原生切换器
BetterCmdTab 用自绘的列表、网格、窗口预览三种布局替换系统自带切换器,支持模糊搜索、固定应用、按应用设置规则等功能。代码全部基于 Swift + AppKit 编写,结构小巧、易于通读。
几个关键特性(详见 CODING_STANDARDS.md):
- 部署目标 macOS 13.0:Liquid Glass 新面板需要 macOS 26 SDK 编译(Xcode 16+),macOS 13–15 运行时自动回退到
NSVisualEffectView - 纯 AppKit:不用 SwiftUI、不用第三方 UI 框架,保证切换器瞬时打开
- 零遥测:唯一的网络请求是可自选的更新检查
- 目录结构:应用源码在 BetterCmdTab/,单元测试在 BetterCmdTabTests/,发布脚本在 scripts/
三种布局中的列表视图,一行对应一个窗口,标题清晰可辨:
1️⃣ 环境准备:一键克隆仓库
前置条件:一台 Mac,安装 Xcode 16+(随 Xcode 26 附带 macOS 26 SDK)。
git clone https://gitcode.com/gh_mirrors/be/BetterCmdTab
cd BetterCmdTab
克隆后可用 Xcode 打开 BetterCmdTab.xcodeproj 浏览。项目预置了两个共享 Scheme(见 BetterCmdTab.xcodeproj/xcshareddata/xcschemes/):
| Scheme | 用途 |
|---|---|
BetterCmdTab Debug |
日常开发、运行单元测试 |
BetterCmdTab |
Release 配置,用于打包发布 |
2️⃣ xcodebuild 构建:一条命令编出 ⌘Tab 切换器
xcodebuild -scheme "BetterCmdTab Debug" -configuration Debug build
参数说明:
-scheme "BetterCmdTab Debug":选择调试 Scheme-configuration Debug:使用调试构建配置- 可选
-derivedDataPath ./build:指定产物目录,便于定位生成的.app
⚠️ 第一次运行必做:启动应用后,在「系统设置 → 隐私与安全性」中授予**辅助功能(Accessibility)**权限。切换器依赖辅助功能 API 枚举应用与窗口(实现在 BetterCmdTab/Catalog/AppCatalog.swift),未授权时按 ⌘Tab 会毫无反应,容易误判为构建失败。
授权后按住 ⌘ 再按 Tab,即可看到自绘的切换面板。网格布局按应用聚合,每个图标下附带窗口信息:
3️⃣ Swift Testing:运行与定位单元测试
项目的测试位于 BetterCmdTabTests/,基于 Swift Testing(import Testing、@Suite / @Test)而非 XCTest,覆盖热键覆盖规划、目录过滤、模糊匹配、切换器状态机、设置导入导出等纯逻辑;UI 需手动验证(切换器离不开辅助功能权限)。
运行完整测试套件:
xcodebuild -scheme "BetterCmdTab Debug" -destination 'platform=macOS' test
只跑单个测试套件:
xcodebuild -scheme "BetterCmdTab Debug" -destination 'platform=macOS' \
test -only-testing:BetterCmdTabTests/FuzzyMatchTests
运行单个测试用例时有一个高频坑:Swift Testing 没有 testXxx 方法,必须用 Swift 函数名加 () 选择。不带 () 的过滤器匹配不到任何用例,但 xcodebuild 仍会报告 Test Succeeded,看似通过实则什么都没跑:
xcodebuild -scheme "BetterCmdTab Debug" -destination 'platform=macOS' \
test '-only-testing:BetterCmdTabTests/FuzzyMatchTests/noMatch()'
测试写法示例(BetterCmdTabTests/SwitcherPhaseTests.swift):
@Suite("Switcher fast-tap rescue")
struct SwitcherReleaseMissedTests {
@Test func missed_whenNeitherHoldModifierDown() {
#expect(SwitcherController.releaseAlreadyMissed(flags: [], appMask: .maskCommand, windowMask: .maskCommand))
}
}
窗口预览布局会为每个窗口渲染实时缩略图,方便在多个同应用窗口间快速定位:
4️⃣ 通读源码:核心文件路径清单
代码库很小,贡献前建议先读这几处(完整列表见 CONTRIBUTING.md):
| 文件 | 职责 |
|---|---|
| BetterCmdTab/Input/HotkeyTap.swift | 全局 CGEvent tap,独立线程捕获 ⌘Tab 组合键并屏蔽系统切换器 |
| BetterCmdTab/Switcher/SwitcherController.swift | 切换器状态机:选择、字母跳转、搜索、Tab 钻取 |
| BetterCmdTab/Switcher/SwitcherView.swift | 列表 / 网格 / 预览三种布局 |
| BetterCmdTab/Switcher/SwitcherPanel.swift | 非激活面板与激活态固定 |
| BetterCmdTab/Windows/MRUTracker.swift | 最近使用(MRU)排序 |
| BetterCmdTab/System/PrivateAPIs.swift | 全部私有 CGS / SkyLight 调用,集中一文件便于审查 |
5️⃣ 发布签名与公证:一个脚本跑完全流程
本地开发构建与对外发布是两回事:发布包必须经过代码签名 → Apple 公证 → 票据装订,才能通过 Gatekeeper。项目把整条流水线封装在 scripts/build_release.sh 中。
前置准备(只需一次):
- 在 Apple Developer 门户安装 Developer ID Application 证书
- 将公证凭据存入钥匙串:
xcrun notarytool store-credentials "BetterCmdTabNotarization" \
--apple-id "your@email.com" \
--team-id "YOUR_TEAM_ID" \
--password "xxxx-xxxx-xxxx-xxxx"
执行发布:
scripts/build_release.sh # 正式版
scripts/build_release.sh --beta # Beta 预发布
脚本内部流程(关键源码见 scripts/build_release.sh):
- 质量门禁:先以 Release 配置、禁用签名的方式编译,由 scripts/release_quality_gate.sh 统计日志,一旦发现 Swift 并发、Sendable、
UnsafeMutableRawPointer等高危警告立即阻断,避免浪费一次存档 + 公证 - Archive:
xcodebuild archive使用 Developer ID 自动签名,产出.xcarchive - Export:以
developer-id方式导出BetterCmdTab.app - 验签:
codesign --verify --deep --strict校验签名、hardened runtime 与 Team ID - 公证:
.app与 DMG 分别经xcrun notarytool submit提交等待审核 - 装订:
xcrun stapler staple把公证票据嵌入产物,用户离线也能通过 Gatekeeper 校验 - 打包:用
ditto与hdiutil生成带 Applications 软链接的 DMG 及 ZIP
最终产物输出到 build/release/,命名为 BetterCmdTab-<版本>-<构建号>.dmg / .zip。版本号管理另有独立脚本:
scripts/set_version.sh --show # 查看当前版本与构建号
scripts/set_version.sh 26.1 # 设置营销版本号
6️⃣ 提交 Pull Request:贡献规范速览
按 CONTRIBUTING.md 与 CODING_STANDARDS.md 的约定,合并前的 PR 需要满足:
- ✅ 遵循编码规范:AppKit only、热路径不进主线程、日志走
Log.* - ✅ 构建无新增警告,全部既有测试通过
- ✅ 新的纯逻辑行为附带至少一个 Swift Testing 用例
- ✅ 提交信息格式
type: short summary(fix:/feat:/perf:/refactor:/docs:/chore:),正文约 72 字符换行并说明为什么 - ✅ 一个 PR 只包含一个逻辑变更,重构与行为变更分开提交
报告 Bug 时附上:macOS 版本(sw_vers 输出)、BetterCmdTab 版本(菜单栏 → About)、精确的按键复现步骤、期望与实际行为对比;崩溃类问题请附带 ~/Library/Logs/DiagnosticReports/ 中的 .ips 文件。
提功能需求请描述想要的工作流而非实现方式——"我想按应用类别过滤切换器"比"加一个类别下拉框"更有价值。
🏁 结语
从克隆到贡献,BetterCmdTab 的完整链路只有三条命令的距离:
# 构建
xcodebuild -scheme "BetterCmdTab Debug" -configuration Debug build
# 测试
xcodebuild -scheme "BetterCmdTab Debug" -destination 'platform=macOS' test
# 发布
scripts/build_release.sh
代码库小、规范清晰、发布流水线透明,是新手切入 macOS 原生应用开发的优质开源项目。建议从修一个文案、补一个测试用例开始,跑通你的第一次贡献。



