需求
界面框架
默认选项
为什么需要
用场景组织 Mac 应用,或实现窗口、侧边栏、工具栏和设置时,SwiftUI 都是合适的首选。
.md 即可查看该页面的 Markdown 版本。
Codex 使用场景
使用 Codex 搭建原生 Mac 应用的 SwiftUI 骨架,并构建和调试应用。
使用 Codex 开发 macOS SwiftUI 应用,并通过 shell 脚本建立可重复执行的构建和运行流程。随着应用逐步完善,您可以添加原生桌面场景和窗口、集成 AppKit,并建立代码签名流程。
使用 Codex 搭建原生 Mac 应用的 SwiftUI 骨架,并构建和调试应用。
使用 Codex 开发 macOS SwiftUI 应用,并通过 shell 脚本建立可重复执行的构建和运行流程。随着应用逐步完善,您可以添加原生桌面场景和窗口、集成 AppKit,并建立代码签名流程。
| 技能 | 使用理由 |
|---|---|
| Build macOS Apps | 主要通过 shell 构建和调试 macOS 应用,用 SwiftUI 设计符合桌面使用习惯的原生场景和窗口,按需桥接 AppKit,并为代码签名和公证做好准备。 |
新建 Mac 应用时,请先让 Codex 选择合适的场景模型:WindowGroup、Window、Settings、MenuBarExtra 或 DocumentGroup。这样,应用从一开始就遵循桌面平台的惯例,无需从 iOS 风格的 ContentView 逐步改造。
优先在 shell 中构建和运行应用。对于 Xcode 项目,请使用 xcodebuild。对于以 Swift 包为基础的应用,请使用 swift build,并在项目内用 script/build_and_run.sh 封装整个流程。脚本会停止旧进程、构建应用并启动新构建的应用,也可以按需输出日志或遥测数据。
如果应用完全使用 SwiftPM 构建,并且有图形界面,请将其打包成 .app 后启动,避免直接运行可执行文件。这样可以避免在本地验证时遇到程序坞中没有应用图标、应用无法激活或系统无法识别应用包等问题。
当开发工作开始涉及更多桌面平台特有的功能时,请添加 Build macOS Apps 插件。它涵盖以 shell 为主的构建和调试流程、SwiftPM 应用打包、SwiftUI 原生场景和窗口的常见用法、与 AppKit 的互操作、统一日志记录、测试故障排查,以及签名和公证流程。
如需了解如何安装和使用插件与技能,请参阅插件文档和技能文档。
优先采用 Mac 的交互惯例,避免照搬 iOS 的导航模式。使用 NavigationSplitView 实现侧边栏与详情并排的布局,为偏好设置单独声明 Settings 场景,通过工具栏和菜单命令让用户容易找到所需操作,并用菜单栏附加项提供随时可用的轻量工具。
优先使用系统材质、语义颜色和标准控件。只有在产品需要独特的桌面界面时,才添加自定义窗口样式、可拖动区域或采用 Liquid Glass 材质的界面元素。
如果 SwiftUI 已能满足大部分需求,请只为缺少的部分添加最小限度的 AppKit 桥接代码。例如,可以用它来调用打开或保存面板、控制第一响应者、验证菜单项是否可用、处理拖放中的特殊情况,或封装一个 NSView 来实现某个专用控件。
要检查应用运行时的行为,请让 Codex 在打开窗口、选择侧边栏项目、执行菜单命令或后台同步时,通过 Logger 记录几个事件。应用启动后,使用 log stream 验证这些事件。
遇到测试失败时,请先让 Codex 用 xcodebuild test 或 swift test 运行足以定位问题的最小测试范围,再判断问题属于哪一类:编译错误、断言失败、崩溃、测试偶发失败,还是环境或配置问题。
当您从本地迭代转向分发应用时,请让 Codex 准备两套流程:一套用于在 Xcode 中手动归档,另一套通过脚本完成归档和公证,便于重复发布。让 Codex 使用 codesign 和 plutil 检查应用包、授权项和强化运行时配置。如果您也想在终端中完成上传,请使用 App Store Connect CLI。
分别为主窗口、设置窗口、辅助工具窗口和菜单栏附加项定义独立的场景根节点,避免把整个应用都放进一个庞大的视图中。
在自定义侧边栏、工具栏或材质之前,请先检查标准 SwiftUI 场景和窗口 API 是否已经支持您需要的 Mac 交互行为。
如果缺少某项桌面功能,可以使用 NSViewRepresentable、NSViewControllerRepresentable 或专门处理该功能的 NSWindow 辅助代码来实现。当前选中项和应用状态仍应由 SwiftUI 统一管理。
应用能在本地成功启动,并不能证明它已签名或已具备公证条件。保留 Xcode 手动归档流程,以便在发布时进行一次性检查。另行添加归档和公证脚本,以便重复分发。当任务进入发布阶段时,除了本地迭代中的检查,还应运行 codesign 和 plutil 进行验证。
需求
默认选项
为什么需要
需求
界面框架
默认选项
为什么需要
用场景组织 Mac 应用,或实现窗口、侧边栏、工具栏和设置时,SwiftUI 都是合适的首选。
需求
AppKit 桥接
默认选项
为什么需要
如果 SwiftUI 无法实现您需要的桌面行为,可以用 NSViewRepresentable、NSViewControllerRepresentable 或 NSWindow 编写少量桥接代码来实现。
需求
构建与打包
默认选项
xcodebuild、swift build 和 App Store Connect CLI
为什么需要
以终端为主要入口,将本地构建、手动归档、通过脚本提交公证以及上传至 App Store 纳入可重复执行的流程。
| 需求 | 默认选项 | 为什么需要 |
|---|---|---|
| 界面框架 | SwiftUI | 用场景组织 Mac 应用,或实现窗口、侧边栏、工具栏和设置时,SwiftUI 都是合适的首选。 |
| AppKit 桥接 | AppKit | 如果 SwiftUI 无法实现您需要的桌面行为,可以用 NSViewRepresentable 、 NSViewControllerRepresentable 或 NSWindow 编写少量桥接代码来实现。 |
| 构建与打包 | xcodebuild 、 swift build 和 App Store Connect CLI | 以终端为主要入口,将本地构建、手动归档、通过脚本提交公证以及上传至 App Store 纳入可重复执行的流程。 |