SweetPad：让 xcodebuild 对人类友好的 Apple 平台开发工具 #

SweetPad 是什么？ #

SweetPad 是一套让开发者不必打开 Xcode 就能构建、运行、调试和测试 Xcode 应用的开源开发工具。它由两个相互独立的产品组成：一是运行在终端里的 sweetpad 命令行工具（CLI），二是把同样的能力搬进侧边栏的 VS Code 扩展。

在 Apple 生态里，xcodebuild 是官方构建入口，但它的输出动辄数百行，错误信息常常被埋在第四十几行。SweetPad 在底层驱动的仍然是 Xcode 自己的构建工具链——同一个编译器、同一套构建系统、同一个 App——只是把落地到终端里的内容从 350 行压缩成 7 行，并且失败时把错误直接放在第三行。它同时支持 Xcode 工程与工作区、Tuist、XcodeGen 以及纯 Swift Package 项目，适用于日常开发、自动化脚本和 CI 流水线。

SweetPad 有哪些亮点特色？ #

• 一行命令跑通整个循环：sweetpad run 会一次性完成构建、安装到指定模拟器或真机、启动应用，并把 os_log、Logger 与标准输出统一流式打印到终端；在会话中按 r 即可原地重建重跑，q 退出，h 查看当前目标支持的快捷键（模拟器和 Mac 上还支持 s 截图、o 前置应用）。

• 可读的构建输出：官方对比数据显示，同一次构建下 xcodebuild 输出 350 行，而 sweetpad 只输出 7 行；构建失败时错误出现在第 3 行而不是第 44 行。对于已被刷屏的终端，还可以用 sweetpad build diagnostics 从磁盘重读上一次构建的报错与警告，瞬间返回且不会重新构建。

• 热重载（Hot Reload）：保存一个 Swift 文件，正在运行的应用就会原地更新，并保持当前界面与状态，无需重新构建、无需重新启动。热重载会使用与构建完全相同的参数重新编译。

• 任意编辑器都能自动补全：一条命令即可把 SourceKit-LSP 接到 SweetPad 的构建服务器上，让补全功能在 Neovim、Zed、Helix 或 Emacs 中正常工作，不需要切换到 Xcode。

• 完整的测试能力：sweetpad test 支持 --only-testing、--skip-testing、--failed、--retry-flaky、--coverage、--junit、--watch 等参数，还可以只编译不运行（sweetpad test build），并能取回失败 UI 测试录下的截图。

• 模拟器与真机全支持：sweetpad devices 按使用频率列出 macOS、模拟器和已连接设备；可以用名称指定模拟器（如 --on "iPhone 16 Pro"）、连接的真机，或 mac、booted。SweetPad 会记住你的选择，只需选一次。

• 面向脚本与 CI 设计：每条命令都支持 JSON 输出并返回有意义的退出码（构建失败为 3、构建中被 Ctrl-C 中断为 6 等），可直接嵌入 git hooks 与流水线。官方还提供供应商中立的 AI agent skill 文件，让编码代理学会驱动 CLI，而不是去猜 xcodebuild 的参数。

• 免费开源，零侵入：基于 MIT 许可证发布，GitHub 超过 1,800 stars，VS Code 扩展安装量超过 61,000 次。除非你主动要求，SweetPad 不会向你的项目写入任何东西，brew uninstall sweetpad 就能把它全部移除。

免费下载 SweetPad #

以下为官方提供的安装包，点击链接即可下载。SweetPad 同时支持 iOS、macOS、tvOS、watchOS、visionOS 五大 Apple 平台，运行环境需要一台装有 Xcode 的 Mac。

提示：CLI 与 VS Code 扩展是两个独立的产品，按需安装其一即可。扩展本身不需要 CLI 也能工作。

SweetPad 如何使用？ #

SweetPad 提供两条使用路径：终端里的 CLI，以及 VS Code（含 Cursor）侧边栏里的扩展。两者做的是同一件事——构建、运行和测试 Xcode 应用。

路径一：使用命令行工具（CLI） #

1. 安装并验证：执行 brew install sweetpad-dev/tap/sweetpad，然后用 sweetpad --version 确认安装成功。整个过程只需要一台装有 Xcode 的 Mac。

2. 准备一个项目：可以从零创建，也可以沿用现有工程。

   • 新建：运行 sweetpad project new，它会用几个简短问题（项目名、iOS 还是 macOS、Bundle Identifier 等）引导你生成一个最小 SwiftUI 应用；想跳过提问就直接 sweetpad project new MyApp --platform ios。
   • 现有：直接 cd 进任意包含 .xcworkspace、.xcodeproj 或 Package.swift 的目录即可，SweetPad 会像 git 一样向父级目录查找工程。

3. 确认当前上下文：运行 sweetpad status 查看 SweetPad 识别到的 scheme 与运行目标。首次使用时它可能还没选定，下一步会自动处理。

4. 构建并运行：执行 sweetpad run。首次会询问使用哪个 scheme、在哪个模拟器或设备上运行，之后会记住答案。想跳过提问可以直接指定，例如 sweetpad run --on "iPhone 16 Pro"。应用启动后日志会实时流入终端。

5. 掌握常用命令：

   sweetpad devices   # 列出所有可运行位置：模拟器、真机、macOS
   sweetpad build     # 只构建，不运行；加 --watch 可在每次保存时重建
   sweetpad test      # 运行测试
   sweetpad format    # 格式化 Swift 源码
   

6. 随时获取帮助：sweetpad --help 列出全部命令，sweetpad run --help 查看单条命令的选项，sweetpad help destinations、sweetpad help config 提供更长的内置指南。

路径二：使用 VS Code 扩展 #

1. 安装 VS Code（若尚未安装），然后从 VS Code Marketplace 安装 SweetPad。Cursor 作为 VS Code 的分支同样适用。
2. 在 VS Code 中打开项目根目录（包含 .xcodeproj 或 .xcworkspace 的那一层），而不是直接打开工程文件本身。
3. 在左侧边栏找到 SweetPad 的棒棒糖图标 🍭，它包含三个区域：Build（scheme 列表，每项带 ▶️ 按钮）、Destinations（模拟器、已连接设备与 macOS）、Tools（一键安装 xcbeautify 等辅助工具）。
4. 点击某个 scheme 旁边的 ▶️，选择目标模拟器或设备，SweetPad 会完成构建、启动模拟器并运行应用。
5. 后续可在扩展中继续配置保存即格式化、断点调试、Testing 面板与 SourceKit-LSP 自动补全。

SweetPad 的常见问题？ #

SweetPad 需要安装 Xcode 吗？ 需要。SweetPad 在底层驱动的就是 Xcode 自带的构建工具链，因此必须在一台装有 Xcode 的 Mac 上运行。它改变的是你与构建系统交互的方式，而不是替换编译器或构建系统。

SweetPad 支持 Windows 或 Linux 吗？ 不支持。无论是 CLI 还是 VS Code 扩展，都依赖 macOS 上的 Xcode 工具链，官方文档明确写明“You need a Mac with Xcode installed”。

CLI 和 VS Code 扩展，我应该装哪个？ 两者是相互独立的产品，能力高度重叠：都在做构建、运行和测试。如果你习惯在终端工作，或者需要把构建接入脚本与 CI，选 CLI；如果你希望有断点调试、原生 Testing 面板、保存即格式化和自动补全，选 VS Code 扩展。扩展不需要 CLI 作为依赖。

SweetPad 会在我的项目里写入文件吗？ 不会。官方明确说明：除非你主动要求，SweetPad 不会向项目中写入任何内容；执行 brew uninstall sweetpad 就能把它全部移除。

构建失败时怎么看具体错误？ 失败时 SweetPad 只打印诊断信息，不再输出冗长的构建流水账，错误会直接出现在前几行。如果终端已被刷屏，可以运行 sweetpad build diagnostics 从磁盘读取上一次构建的错误与警告，该命令无需重新构建、可以反复执行。需要原始输出时加 -v 参数即可看到 xcodebuild 的全部内容。

它支持哪些项目类型？ 支持 Xcode 工程与工作区、Tuist、XcodeGen 生成的项目，以及纯 Swift Package。此外还提供 git merge driver，能以语义方式解决 .pbxproj 冲突（参考官方文档说明）。

SweetPad 如何安装？ #

macOS —— 命令行工具（CLI） #

1. 确认已安装 Xcode 与 Homebrew。
2. 在终端执行：

   brew install sweetpad-dev/tap/sweetpad
   

3. 验证安装：

   sweetpad --version
   

4. 如需诊断本地工具链状态，可运行 sweetpad doctor。

macOS —— VS Code / Cursor 扩展 #

1. 安装 VS Code（Cursor 亦可）。
2. 打开扩展面板，搜索 SweetPad，或从 VS Code Marketplace 页面点击安装。
3. 也可以直接使用本文下载表格中的 sweetpad-0.2.18.vsix 离线安装包：在 VS Code 中打开扩展面板右上角菜单，选择“从 VSIX 安装…”，然后选中该文件。
4. 若下载的是 sweetpad-cli-0.1.12-macos-universal.tar.gz，解压后按其中的二进制说明放置到 PATH 路径下即可（该包为 macOS 通用二进制，同时适配 Apple 芯片与 Intel 芯片）。

SweetPad 如何卸载？ #

卸载命令行工具（CLI） #

在终端执行：

brew uninstall sweetpad

官方说明：SweetPad 不会向你的项目写入任何内容，因此 brew uninstall sweetpad 就能把它彻底移除。

如果你曾用 sweetpad doctor 或构建过程生成过本地状态缓存，SweetPad 的结果文件默认存放在用户目录下的本地状态路径（例如 ~/.local/state/sweetpad/results/），如需彻底清理可手动删除该目录。

卸载 VS Code / Cursor 扩展 #

1. 打开 VS Code 的扩展面板；
2. 在已安装列表中找到 SweetPad；
3. 点击“卸载”，重启编辑器生效。

如果曾通过扩展的 Tools 面板安装过 xcbeautify 等辅助工具，需要单独卸载（例如通过 Homebrew 执行 brew uninstall xcbeautify），扩展卸载不会自动移除这些第三方工具。