如何从零构建BetterCmdTab并参与开源贡献?xcodebuild、Swift Testing与发布签名完整指南

原创2026-10-25 14:04:502,226 阅读

如何从零构建BetterCmdTab并参与开源贡献?xcodebuild、Swift Testing与发布签名完整指南

BetterCmdTab 是一个完全开源的 macOS ⌘Tab 应用切换器项目。这篇指南带你用 xcodebuild 从零完成项目构建、Swift Testing 单元测试运行与发布签名,并覆盖开源贡献的关键步骤。全程命令行驱动,无需图形界面操作。

🧭 先认识 BetterCmdTab:轻量的原生切换器

BetterCmdTab 用自绘的列表、网格、窗口预览三种布局替换系统自带切换器,支持模糊搜索、固定应用、按应用设置规则等功能。代码全部基于 Swift + AppKit 编写,结构小巧、易于通读。

BetterCmdTab 开源 macOS ⌘Tab 应用切换器产品概览图

几个关键特性(详见 CODING_STANDARDS.md):

  • 部署目标 macOS 13.0:Liquid Glass 新面板需要 macOS 26 SDK 编译(Xcode 16+),macOS 13–15 运行时自动回退到 NSVisualEffectView
  • 纯 AppKit:不用 SwiftUI、不用第三方 UI 框架,保证切换器瞬时打开
  • 零遥测:唯一的网络请求是可自选的更新检查
  • 目录结构:应用源码在 BetterCmdTab/,单元测试在 BetterCmdTabTests/,发布脚本在 scripts/

三种布局中的列表视图,一行对应一个窗口,标题清晰可辨:

BetterCmdTab ⌘Tab 切换器列表视图截图

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,即可看到自绘的切换面板。网格布局按应用聚合,每个图标下附带窗口信息:

BetterCmdTab ⌘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))
    }
}

窗口预览布局会为每个窗口渲染实时缩略图,方便在多个同应用窗口间快速定位:

BetterCmdTab 切换器窗口预览模式实时缩略图截图

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 中。

前置准备(只需一次):

  1. 在 Apple Developer 门户安装 Developer ID Application 证书
  2. 将公证凭据存入钥匙串:
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):

  1. 质量门禁:先以 Release 配置、禁用签名的方式编译,由 scripts/release_quality_gate.sh 统计日志,一旦发现 Swift 并发、Sendable、UnsafeMutableRawPointer 等高危警告立即阻断,避免浪费一次存档 + 公证
  2. Archive:xcodebuild archive 使用 Developer ID 自动签名,产出 .xcarchive
  3. Export:以 developer-id 方式导出 BetterCmdTab.app
  4. 验签:codesign --verify --deep --strict 校验签名、hardened runtime 与 Team ID
  5. 公证:.app 与 DMG 分别经 xcrun notarytool submit 提交等待审核
  6. 装订:xcrun stapler staple 把公证票据嵌入产物,用户离线也能通过 Gatekeeper 校验
  7. 打包:用 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 原生应用开发的优质开源项目。建议从修一个文案、补一个测试用例开始,跑通你的第一次贡献。

登录后查看全文
BetterCmdTab