> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Devin macOS 支持

> 在配备 Xcode 和 iOS 模拟器的 macOS 虚拟机上运行 Devin，构建、运行并测试 Apple 平台应用。

Devin 现已支持使用 macOS 虚拟机，因此可以构建和测试 iOS 与 macOS 应用程序。

<Note>
  如果你使用的是 Dedicated SaaS 部署，请联系你的账户团队以启用 macOS 虚拟机。
</Note>

<div id="how-it-works">
  ## 工作原理
</div>

macOS 支持构建在与 Linux 相同的[声明式配置](/zh/onboard-devin/environment/blueprints)系统之上。蓝图中的 `runs-on` 字段用于告诉 Devin 在哪个平台上构建和运行，每个平台都有各自独立的快照。

与 Linux 的主要区别在于 shell、文件系统布局和包管理器：

| 方面     | Linux (默认)             | macOS                                |
| ------ | ---------------------- | ------------------------------------ |
| 主目录    | `/home/ubuntu`         | `/Users/devin`                       |
| 代码仓库目录 | `~/repos/<repo-name>`  | `/Users/devin/repos/<repo-name>`     |
| Shell  | `bash`                 | `zsh`                                |
| 包管理器   | `apt-get`              | `brew` (Homebrew 位于 `/opt/homebrew`) |
| 文件附件   | `/home/ubuntu/.files/` | `/Users/devin/.files/`               |

<div id="starting-a-macos-session">
  ## 启动 macOS 会话
</div>

你可以为每个会话单独选择 macOS：

* **蓝图**：添加 `runs-on: macos`，让该仓库的快照针对 macOS 构建 (见下文) 。
* **Slack**：使用 `!mac` [bang 命令](/zh/integrations/slack) 在 macOS 虚拟机上启动会话。
* **API**：在创建会话、计划或自动化任务时设置 `platform: "macos"`。参见 [API 参考](/zh/api-reference/overview)。

<div id="writing-macos-blueprints">
  ## 编写 macOS 蓝图
</div>

<div id="single-platform-blueprint">
  ### 单平台蓝图
</div>

如果你的代码仓库仅面向 Apple 平台，请在顶层使用 `runs-on: macos`：

```yaml theme={null}
runs-on: macos

initialize:
  - name: "Install build tooling"
    run: |
      brew install xcodegen swiftlint xcbeautify

maintenance: |
  xcodebuild -resolvePackageDependencies -project MyApp.xcodeproj -scheme MyApp

knowledge:
  - name: build
    contents: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' build
  - name: test
    contents: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' test
  - name: lint
    contents: swiftlint
```

<div id="multi-platform-blueprint">
  ### 多平台蓝图
</div>

若要为多个平台构建同一个代码仓库，请将每个平台写成独立的 YAML 文档，并以 `---` 分隔。每个文档各自声明自己的 `runs-on` 标签。有关该格式的背景信息，请参阅蓝图指南中的 [Multi-document YAML](/zh/onboard-devin/environment/blueprints#blueprint-sections) 提示框。

```yaml theme={null}
runs-on: default
initialize: |
  apt-get update && apt-get install -y build-essential

maintenance: |
  npm install

knowledge:
  - name: test
    contents: npm test

---
runs-on: macos
initialize: |
  brew install cocoapods

maintenance: |
  npm install
  (cd ios && pod install)

knowledge:
  - name: test
    contents: npm test
```

每个文档都会为其对应平台生成独立的快照构建。会话将从对应平台的快照启动。

<Warning>
  顶层 YAML 必须是 mapping，而不是序列。如果将上面的示例写成单个列表 (`- runs-on: default` / `- runs-on: macos`) ，后端会 reject。请使用上面所示的 `---` 分隔符。
</Warning>

<div id="the-runs-on-field">
  ## `runs-on` 字段
</div>

`runs-on` 字段映射到你账户中已注册的机器配置：

| 值                   | 平台           |
| ------------------- | ------------ |
| `default` 或 `linux` | Linux (默认平台) |
| `macos`             | macOS        |
| `windows`           | Windows      |

你可以将 `runs-on` 指定为字符串或列表：

```yaml theme={null}
# 单个平台
runs-on: macos

# 在一个块中指定多个平台（每个平台上运行相同的命令）
runs-on: [default, macos]
```

<Warning>
  列表语法会在列表中的每个平台上运行完全相同的命令。仅当命令确实跨平台时 (例如 `npm install`) 才使用这种写法。对于特定平台的命令 (如 Linux 上的 `apt-get` 或 macOS 上的 `brew`) ，请改用[多文档格式](#multi-platform-blueprint)。
</Warning>

<div id="usage-and-cost">
  ## 用量与成本
</div>

macOS 会话消耗的用量与同等的 Linux 或 Windows 会话相同，不收取 macOS 附加费用。有关用量计量方式的详细信息，请参阅[用量](/zh/admin/billing/usage#macos-sessions)。

<div id="whats-preinstalled">
  ## 预装内容
</div>

macOS 会话镜像已预装 Apple 工具链，因此你的蓝图无需再自行下载：

| 类别       | 已包含                                                                                                         |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| Xcode    | 默认为最新的 Xcode 26 正式版，位于 `/Applications/Xcode.app`，并同时提供 Xcode 27 预发布版 (例如 `/Applications/Xcode-27.0-RC.app`) |
| 模拟器      | 每个已安装的 Xcode 各配一个 iOS 模拟器运行时 (iOS 26 和 iOS 27) ，并预先配置好一台 iPhone 设备                                          |
| Apple 工具 | `xcodebuild`、`xcrun`、`simctl`、Swift 以及 Metal 工具链                                                            |
| 包管理器     | 位于 `/opt/homebrew` 的 Homebrew                                                                               |
| 语言       | Node.js、Python、Java、Rust (以及 `npm`、`yarn`、`pnpm`)                                                           |
| CLI 工具   | `git`、`git-lfs`、`gh`、`jq`、`ripgrep`、`ffmpeg`、`wget`、`direnv`                                                |
| 浏览器      | Google Chrome                                                                                               |

随着 Apple 发布新版本、镜像随之更新，各组件版本也会变化。要确切了解某个会话中的版本情况，可让 Devin 运行：

```bash theme={null}
sw_vers
xcodebuild -version
ls -d /Applications/Xcode*.app
xcrun simctl list runtimes
```

<div id="selecting-an-xcode-version">
  ### 选择 Xcode 版本
</div>

默认的 Xcode 即 `xcode-select` 所指向的版本。若只想在单条命令中使用其他已安装的版本，请设置 `DEVELOPER_DIR`：

```bash theme={null}
DEVELOPER_DIR=/Applications/Xcode-27.0-RC.app/Contents/Developer /usr/bin/xcodebuild -version
```

请使用 `/usr/bin/xcodebuild`(该 shim 会遵循 `DEVELOPER_DIR`),而不是通过 `PATH` 解析到的某个特定 Xcode 的 `Contents/Developer/usr/bin` 下的 `xcodebuild`,因为后者无论 `DEVELOPER_DIR` 如何设置,都只会报告自身的版本。

或者为整个会话切换默认版本:

```bash theme={null}
sudo xcode-select -s /Applications/Xcode-27.0-RC.app
```

在蓝图中写入你需要的版本，这样每个会话启动时都会使用正确的工具链。

<div id="macos-session-behavior">
  ## macOS 会话行为
</div>

<div id="shell">
  ### Shell
</div>

macOS 会话使用 **zsh** 作为默认 shell。大多数 POSIX shell 命令可直接沿用 Linux 蓝图中的写法，无需修改，但需注意 BSD 用户态工具的差异：`sed -i` 必须带一个参数 (`sed -i ''`) ，而 `gsed`、`gdate`、`greadlink` 等 GNU 工具需通过 Homebrew 的 `coreutils` formula 安装。

<div id="paths">
  ### 路径
</div>

```yaml theme={null}
# Linux 路径
- run: cp config.json ~/.config/myapp/config.json

# macOS 路径
- run: cp config.json /Users/devin/.config/myapp/config.json
```

仓库会被克隆到 `/Users/devin/repos/<repo-name>`，你上传到会话中的文件则会写入 `/Users/devin/.files/`。

<div id="secrets">
  ### Secrets
</div>

[Secrets](/zh/product-guides/secrets) 在会话期间以环境变量的形式提供 (`$SECRET_NAME`) ，与 Linux 上的行为一致。可通过这种方式提供 App Store Connect API 密钥、签名凭据或私有 registry 令牌：

```yaml theme={null}
maintenance:
  - name: "Configure private Swift package registry"
    run: |
      git config --global url."https://$GIT_TOKEN@github.com/".insteadOf "https://github.com/"
```

<div id="session-sleep-and-wake">
  ### 会话休眠与唤醒
</div>

会话休眠时会将磁盘内容保存为快照。磁盘上的所有内容在唤醒后依然保留：已安装的工具、已克隆的代码仓库、构建缓存和派生数据。但正在运行的进程不会保留：开发服务器、模拟器和文件监听器需要在会话唤醒后重新启动。

<div id="computer-use">
  ### Computer Use
</div>

[Computer Use](/zh/work-with-devin/computer-use) 支持 macOS 会话：Devin 可获得一个完整的 macOS 桌面，配备 Chrome、鼠标和键盘，既能测试 macOS 原生应用，也能测试 Web 应用，并可将操作过程[录制](/zh/work-with-devin/testing-and-recordings)下来。在 macOS 上，Devin 使用 Command 键触发快捷键 (⌘C、⌘V、⌘Tab) ，而非 Control 键。

<div id="ios-simulator">
  ### iOS 模拟器
</div>

Devin 可以直接启动并操控 iOS 模拟器：

```bash theme={null}
open -a Simulator                  # 启动默认设备
xcrun simctl list devices          # 查看可用设备
xcrun simctl boot "iPhone 17"      # 启动指定设备
xcrun simctl install booted MyApp.app
xcrun simctl launch booted com.example.MyApp
```

会话 workspace 中的 **iOS Simulator** 选项卡会实时串流已启动的模拟器画面，让你可以实时观看 Devin 在你的 app 中逐步点击操作。这相当于 Apple 平台版的 [Android emulator support](/zh/onboard-devin/environment/android-emulation)。

<div id="tips-tricks">
  ## 使用技巧
</div>

<div id="warm-build-caches">
  ### 预热构建缓存
</div>

冷构建 Xcode 会拖慢构建速度，影响开发体验。可使用 `environment.yml` 中的 `maintenance` 字段预热缓存。

```yaml theme={null}
runs-on: macos

initialize:
  - name: "Install tooling"
    run: brew install cocoapods xcodegen swiftlint

maintenance:
  - name: "Resolve dependencies and warm the build"
    run: |
      xcodebuild -resolvePackageDependencies -project MyApp.xcodeproj -scheme MyApp
      xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17' build-for-testing
  - name: "Pre-boot the simulator"
    run: xcrun simctl boot "iPhone 17" || true
```

已解析的 Swift 软件包、CocoaPods 和 DerivedData 都会保留在快照中，因此新会话可以直接从增量构建开始。

<div id="network-access">
  ### 网络访问
</div>

如果构建过程需要从 CocoaPods、Swift Package Manager、Firebase 或私有 registry 拉取依赖，就必须能访问这些主机。如果你的组织启用了受限的网络策略，请确保 macOS 允许列表中也包含 Linux 构建所使用的那些 registry。两者需要分别配置，一旦遗漏某个条目，通常会在构建中途表现为依赖解析失败或 TLS 失败。

<div id="running-containers">
  ### 运行容器
</div>

macOS 虚拟机不支持嵌套硬件虚拟化，因此容器运行时只能回退到 QEMU 的软件模拟 (TCG) 。Colima 会自动检测并切换到模拟模式：

```bash theme={null}
brew install colima docker qemu lima
colima start --vm-type qemu --arch aarch64 --cpu 4 --memory 8 --disk 30
```

虚拟机需要两到四分钟才能进入可用状态；首次启动时，模拟的客户机正在配置网络，等待 SSH 的过程可能会超时，如果 `colima start` 失败，重试即可。启动之后，container 在 CPU 上的运行速度约为原生的 1/15 到 1/25，每次启动还需几秒；镜像拉取则可跑满宿主机网络速度。用来跑 lint 或打包类 container 没什么问题，但拿来编译就很折磨了。如果工作中大量使用 container，建议改用 Linux 会话，或让 macOS 会话指向远程的 Docker 守护进程。

<div id="dont-install-xcode-in-a-blueprint-unless-you-have-to">
  ### 非必要不要在蓝图中安装 Xcode
</div>

Xcode 下载体积多达数 GB，而且 Apple 要求登录 Apple ID 才能下载。建议优先使用 image 中已有的版本，通过 `DEVELOPER_DIR` 或 `xcode-select` 来选择。如果确实需要其他版本或测试版，可以把 Apple ID 存为 [secret](/zh/product-guides/secrets)，让蓝图去下载该版本，但代价是构建会慢很多。

<div id="limitations">
  ## 限制
</div>

| 限制         | 详情                                                      |
| ---------- | ------------------------------------------------------- |
| Docker 与容器 | 不支持嵌套硬件虚拟化，因此容器以软件模拟方式运行。参见[运行容器](#running-containers)。 |
| 物理设备       | 不支持 USB 直通，因此构建和测试均在模拟器上运行，而非真实的 iPhone 或 iPad。         |
| Xcode 下载   | 获取其他 Xcode 版本或模拟器运行时需提供 Apple ID 凭据，且下载耗时较长。            |
| 性能测量       | 在虚拟机中使用 Instruments 类工具进行计时与性能分析，无法反映真实设备的性能表现。         |

<div id="troubleshooting">
  ## 故障排查
</div>

**快照重建后的第一个会话中,构建明显变慢。** 这是因为 DerivedData 被从零重新构建了。可在 `maintenance` 中添加一次 `build-for-testing` 步骤,让快照带上已预热的构建产物。

**`xcodebuild` 选用了错误的工具链。** 检查 `xcode-select -p`,并在蓝图步骤中显式设置 `DEVELOPER_DIR`。

**找不到指定的 destination。** 运行 `xcrun simctl list devices available`,查看已安装的运行时实际提供了哪些设备,并让 `-destination` 中的名称和系统版本与之匹配。

**依赖解析卡住,或因 TLS 错误而失败。** 通常是该主机不在你的组织针对 macOS 的网络允许列表中。参见[网络访问](#network-access)。