---
title: "构建 macOS 应用"
description: "说明用 Codex 构建 macOS app 时，如何从 scene、window、menus、settings 和 desktop UX 出发。"
verifiedAt: "2026-05-05"
---

用 Codex 构建 macOS app，要先按 Mac 的 scene、window、menus、settings 和 desktop UX 思考，而不是从一个 iOS-style `ContentView` 开始。执行上保持 shell-first：Xcode project 用 `xcodebuild`，package-first app 用 `swift build`，再用项目内 `script/build_and_run.sh` 统一本地验证。

官方页面：[https://developers.openai.com/codex/use-cases/native-macos-apps](https://developers.openai.com/codex/use-cases/native-macos-apps)

## 适合什么任务

| 场景 | Codex 应该做什么 |
|---|---|
| greenfield macOS SwiftUI app | scaffold desktop-native app shell 和 repeatable build script |
| 现有 Mac app 需要改 windows、menus、sidebars、settings、AppKit interop 或 signing | 按 Mac UX convention 修改并验证 |
| 团队希望 macOS 工作保持 shell-first | 用 terminal build/test/log loop，同时尊重 native desktop conventions |

## 使用的能力

| 能力 | 用法 | 链接 |
|---|---|---|
| `build-macos-apps` | 用 shell-first workflow 构建和调试 macOS apps，设计 desktop-native SwiftUI scenes/windows，需要时接 AppKit，并准备 signing/notarization paths | [https://github.com/openai/plugins/tree/main/plugins/build-macos-apps](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps) |

相关官方说明：

- Model Context Protocol：[https://developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示词

```text
请使用 Build macOS Apps plugin，scaffold 一个 starter macOS SwiftUI app，并添加项目本地 `script/build_and_run.sh` entrypoint，方便我接到 `Run` action。

约束：
- 保持 shell-first。Xcode projects 优先使用 `xcodebuild`，package-first apps 使用 `swift build`。
- 显式建模 Mac scenes：main window 加 `Settings`、`MenuBarExtra` 或 utility windows；只有符合产品时才加入后者。
- 优先使用 desktop-native sidebars、toolbars、menus、keyboard shortcuts 和 system materials，不要用 iOS-style push navigation。
- 只有 SwiftUI 无法干净表达 desktop behavior 时，才使用窄 AppKit bridge。
- 每次 change 保持一个小 validation loop，并准确告诉我运行了哪些 build、launch 或 log commands。

交付：
- app scaffold 或 requested Mac feature slice
- 可复用 build-and-run script
- 你运行过的最小 validation steps
- 你建议的 desktop-specific follow-up work
```

这个 prompt 的关键是先选 scene model，再搭 build/run loop。

## 推荐技术面

| 需要 | 推荐默认值 | 原因 |
|---|---|---|
| UI framework | [SwiftUI](https://developer.apple.com/documentation/swiftui/) | 适合 windows、sidebars、toolbars、settings 和 scene-driven Mac app structure |
| AppKit bridge | [AppKit](https://developer.apple.com/documentation/appkit) | SwiftUI 表达不到某个桌面行为时，用小 `NSViewRepresentable`、`NSViewControllerRepresentable` 或 `NSWindow` bridge |
| Build and packaging | `xcodebuild`、`swift build`、[App Store Connect CLI](https://asccli.sh/) | 保持 local builds、manual archives、script-based notarization、App Store uploads 的 terminal-first loop |

## Scaffold App 和 Build Loop

新 Mac app 第一件事是让 Codex 选择 scene model：

- `WindowGroup`
- `Window`
- `Settings`
- `MenuBarExtra`
- `DocumentGroup`

执行 loop 保持 shell-first。Xcode projects 用 `xcodebuild`；package-first apps 用 `swift build`；项目内加 `script/build_and_run.sh`，负责停止旧进程、build app、launch 新 artifact，并按需暴露 logs 或 telemetry。

如果纯 SwiftPM app 是 GUI app，要 bundle 并 launch 为 `.app`，不要直接运行 raw executable。否则本地验证可能遇到 Dock、activation、bundle identity 问题。

## 使用 Build macOS Apps Plugin

当任务进入 desktop-specific 层面时，加入 [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps)。它覆盖：

- shell-first build/debug loops。
- SwiftPM app packaging。
- native SwiftUI scene/window patterns。
- AppKit interop。
- unified logging。
- test triage。
- signing/notarization workflows。

## 构建 Desktop-Native UI

优先用 Mac conventions：

- `NavigationSplitView` 做 sidebar/detail。
- `Settings` scene 放 preferences。
- toolbars 和 commands 暴露可发现 actions。
- menu bar extras 做轻量常驻工具。

先用 system materials、semantic colors 和 standard controls。custom window styling、drag regions 或 Liquid Glass surfaces 只有产品需要时再加。

如果 SwiftUI 只差一点，用最小 AppKit bridge 补缺口，例如 open/save panels、first-responder control、menu validation、drag-and-drop edges，或一个特定 `NSView`。

## Debug、Test、Ship

runtime 行为不清楚时，让 Codex 围绕 window opening、sidebar selection、menu commands 或 background sync 加少量 `Logger` events，然后用 `log stream` 验证。

tests 失败时，先跑最小有用范围的 `xcodebuild test` 或 `swift test`，并分类：

- compilation。
- assertion failure。
- crash。
- flake。
- environment/setup problem。

进入 distribution 时，让 Codex 同时准备：

- Xcode manual archive path。
- script-based archive and notarization path。
- `codesign` 和 `plutil` 检查 app bundle、entitlements、hardened runtime。
- 需要 terminal upload 时，用 [App Store Connect CLI](https://asccli.sh/)。

## 实用建议

- main window、settings window、utility windows、menu bar extras 建成 separate scene roots。
- 标准 SwiftUI scene/window APIs 能解决时，不要先写 custom chrome。
- AppKit 只做窄边缘，SwiftUI 仍是 selection 和 app state 的 source of truth。
- local launch 成功不等于 app 已签名或已准备 notarization；发布相关任务要单独检查。
