在 Omarchy 上构建、调试并热重载 iPhone 应用

在 Linux（Omarchy）上构建、运行、调试和实时编辑 iPhone 应用。无需 Mac。

这套工具将装有 omarchy-apple-dev（它会安装 Swift、Apple 的 iOS SDK 和 xtool）的 Linux 机器变成完整的日常 iPhone 开发环境：

在 Linux 上你无法获得：iOS 模拟器、SwiftUI 预览（真机上的热重载可替代它们）、Interface Builder 和 Instruments。手机通过 USB 数据线连接。

每一步都在真实 iPhone 上测试过，沿途发现的每一个坑都记录在这里以及 docs/HOW-IT-WORKS.md 中，这样你就不必再重新踩一遍。

目录

1. 测试环境
2. 你需要什么
3. 安装工具链（omarchy-apple-dev）
4. 安装本套件
5. 你的第一个应用
6. 调试
7. 热重载
8. 日常使用速查表
9. 编码代理（AGENTS.md）
10. 保持其正常工作
11. 故障排除
12. Intel Mac 及其他机器
13. 卸载
14. 致谢与许可

1. 测试环境

其他版本很可能也能用；以上是本文每一步实际运行所用的版本。

2. 你需要什么

• 一台运行 Omarchy 的 Linux 机器（其他基于 Arch 的环境也很接近；Omarchy 特有的部分是可选按键和 Lua Hyprland 配置）。
• 一部 iPhone 和一根 USB 数据线（不是仅充电线）。在当前 iOS 上，从 Linux 进行无线安装不可行。
• 一个 Apple Developer 账户。本文测试使用的是付费计划（$99/年）：安装有效期约为一年，并且你可以使用 App Store Connect API 密钥和 TestFlight。xtool 也接受免费 Apple ID（7 天安装有效期，功能较少）；该路径未经本文测试。
• 与你的 Swift 版本匹配的 Xcode .xip，使用任意（免费）Apple ID 从 Apple 下载：参见 3.4。只从中提取 SDK；Xcode 从不运行。
• 磁盘空间：工具链和 SDK 约需 10 GB，此外你调试的每个 iOS 版本约需 6 GB（调试符号，在首次调试运行时自动生成）。
• VS Code（可选但推荐），并安装扩展 Swift（swiftlang.swift-vscode）和 LLDB DAP（llvm-vs-code-extensions.lldb-dap）。

3. 安装工具链（omarchy-apple-dev）

omarchy-apple-dev 承担了繁重的工作（Swift、SDK、xtool、pymobiledevice3）。 也请阅读它的 README；这些是在其基础上总结出的步骤和经验教训。

3.1 Swift 和 Xcode 必须匹配

Linux 上的 Swift 编译器必须与 Apple 用于该 SDK 的版本相同： Swift 6.4 ↔ Xcode 27，Swift 6.3 ↔ Xcode 26。版本不匹配会导致每次构建都失败 （“此 SDK 不受编译器支持”）。请查看 omarchy-apple-dev 的 README 了解其当前版本对照表。

3.2 克隆它

git clone https://github.com/joshuaswarren/omarchy-apple-dev ~/Tools/omarchy-apple-dev

任何文件夹都可以（该工具包会询问位置）。不要把它放在 ~/.local/share/omarchy-apple-dev 中：未来 Omarchy 菜单中针对 iOS 的条目 （撰写时上游尚待添加）在移除 iOS 支持时会复用并删除该 文件夹。

3.3 安装前先锁定 swift-bin（推荐）

AUR 的 swift-bin 包绝不能自行更新：一次常规的系统 更新到新的 Swift 版本后，将不再与你的 SDK 匹配。请先锁定它：

sudo sed -i '/^HoldPkg/a IgnorePkg   = swift-bin' /etc/pacman.conf

（该工具包的 install.sh 也提供此功能。当你选择升级时，ios-toolchain-upgrade 会 正确执行升级；见 10.1。）

3.4 下载 Xcode（SDK 来自其中）

Apple 仅在 Xcode 内提供 iOS SDK，因此你需要下载一次 Apple 的 Xcode_<version>.xip。不会从中安装或运行任何东西： 安装程序只是把 SDK 取出来。你不需要 Mac。

1. 在浏览器中打开 https://developer.apple.com/download/all/?q=Xcode 并使用任意 Apple ID 登录。免费账号就足以完成这次 下载；如果 Apple 要求，请接受开发者协议。
2. 选择与你的 Swift 匹配的 Xcode（3.1）。Swift 6.4 需要 Xcode 27：选择名为“Xcode 27”的正式发布条目（除非你的 Swift 需要， 否则不要选 beta 或候选发布版）。忽略“Command Line Tools”、 “Additional Tools”和模拟器运行时。
3. 点击该条目中的 .xip 文件。Xcode 27 的约 2 GB；更早的 版本更大。保存它，例如保存为 ~/Downloads/Xcode_27.xip。 不要解压它；安装程序会直接读取 .xip。
4. 检查文件大小。Apple 的下载需要浏览器登录，因此 在未登录的情况下对链接使用 wget/curl 只会保存一个小的 HTML 页面，而不是 真正的文件。如果文件只有几 KB，请从浏览器中下载。

不确定是哪个版本？在不带 XCODE_XIP 的情况下运行一次 omarchy-apple-dev 的安装程序： 它会在 SDK 步骤停止，并打印出确切的 Xcode 名称和 链接。如果你已经有一台装有匹配 Xcode 的 Mac，omarchy-apple-dev 也可以 仅从其中流式传输 SDK 组件（其 install-toolchain.sh 中的“Route B”）。

之后请保留 .xip（放在任何位置，甚至外置硬盘）：以后重新安装 或修复 SDK 不需要它（SDK 已缓存），但全新的 机器或损坏的缓存则需要。

3.5 运行安装程序

在下载好 .xip 后（3.4）：

cd ~/Tools/omarchy-apple-dev
PATH="/usr/bin:$PATH" XCODE_XIP=~/Downloads/Xcode_27.xip ./install-toolchain.sh --mode full

• PATH="/usr/bin:$PATH" 会让安装程序在系统 Python 上构建其 Python 环境 （~/pymobile3-venv）。如果你使用 mise/asdf/pyenv， 它们的“最新”Python 之后可能会升级到新版本并破坏该 环境。
• 如果安装程序警告三个 .xcspec 文件“不可写”，那是 预期情况：它们属于 swift-bin 包（root）。该工具包的安装程序 （或 ios-toolchain-upgrade --patch）会用 sudo 应用这三个补丁。 没有它们，带有 .strings 文件的应用将无法构建。

3.6 登录 Apple

xtool 需要登录一次你的 Apple 账户，以创建用于签署应用的开发 证书和描述文件。它提供两种方式； 任选其一。

选项 A：App Store Connect API 密钥（需要付费的 Apple Developer Program；该工具包就是用这种方式测试的，同一个密钥之后也可用于 TestFlight 上传）：

1. 前往 App Store Connect → Users and Access → Integrations → App Store Connect API。在 Team Keys 下，点击 +（账户持有人可能首先需要在那里申请 API 访问权限）。
2. 为密钥命名并指定角色。选择 Admin：这是最简单的选择，可以创建证书和描述文件。
3. 下载密钥：一个名为 AuthKey_<KEY ID>.p8 的文件。 Apple 只允许你 下载一次，所以请妥善保管；如果丢失，请撤销它并 重新创建一个。
4. 记下该页面上显示的两个 ID：Key ID（在密钥旁边）和 Issuer ID（在密钥列表顶部）。
5. Store the key privately:

   mkdir -p ~/.appstoreconnect/private_keys
   mv ~/Downloads/AuthKey_*.p8 ~/.appstoreconnect/private_keys/
   chmod 700 ~/.appstoreconnect ~/.appstoreconnect/private_keys
   chmod 600 ~/.appstoreconnect/private_keys/AuthKey_*.p8

6. 运行 xtool auth，选择 API key 选项，并填入 Issuer ID、 Key ID 以及 .p8 文件的路径。

选项 B：你的 Apple ID（免费账户也可使用）：

1. 运行 xtool auth 并选择 Apple ID 选项。
2. 输入你的 Apple ID 邮箱和密码，然后输入 Apple 发送到你设备上的双重验证码。

使用免费账户时，以这种方式安装的应用会在 7 天后过期，而且 Apple 会限制你能拥有的数量；该套件尚未在此路径上测试过。

无论哪种方式， xtool 都会将其令牌存储在 ~/.config/xtool/data/ 中，并且可能创建为 其他人可读；请收紧权限：

chmod 700 ~/.config/xtool ~/.config/xtool/data
chmod 600 ~/.config/xtool/data/*

3.7 连接手机

1. 将 iPhone 插上，解锁，点击 Trust 并输入密码。
2. 检查它是否被识别：~/pymobile3-venv/bin/pymobiledevice3 usbmux list。
3. 必须开启 Developer Mode 才能运行你自己的应用（iOS 16+）：设置 → 隐私与安全性 → 开发者模式（可能只有在首次 安装应用后才会出现；开启后手机会重启）。

4. 安装套件（此仓库）

git clone https://github.com/JonathanInTheClouds/omarchy-ios-kit.git ~/Tools/omarchy-ios-kit
cd ~/Tools/omarchy-ios-kit
./install.sh

安装程序会：

1. 检查第 3 节中的先决条件（以及 inotify-tools，热重载 所需：sudo pacman -S inotify-tools）。
2. Asks your settings and saves them in ~/.config/ios-run/config:
   • 你的 bundle ID 前缀（你控制的反向域名，例如 com.yourname；应用会变成 com.yourname.MyApp）；
   • 你的应用文件夹（默认 ~/Projects/ios）；
   • omarchy-apple-dev 克隆到的位置；
   • 你存放 Xcode 下载文件的位置。
3. 安装 ios-run、ios-run-dev、new-ios-app 和 ios-toolchain-upgrade 到 ~/.local/bin，并将热重载包、 模板、工具和这些文档安装到 ~/.local/share/ios-run/。
4. Offers, one by one (each is optional and explained):
   • 保留 swift-bin（3.3）；
   • 让 usbmuxd 在崩溃后自行重启（它可能会在 调试会话前后中止）；
   • .xcspec 补丁（3.5）；
   • VS Code 快捷键（F6 运行，Ctrl+Alt+D 调试），合并到你的 键位绑定中并保留备份；
   • Omarchy 按键 SUPER+R / SUPER+SHIFT+R（作为标记块追加到 ~/.config/hypr/bindings.lua，如果你已使用这些按键则跳过）；
   • 为你的编码代理（Claude Code、Codex）指向这些 文档的简短指引。
5. 告知你关于 热重载签名身份 的信息（7.1）。

随时再次运行 ./install.sh 进行更新；你的设置会保留。 --yes 接受所有可选步骤，--no-system 跳过需要 sudo 的步骤。

5. 你的第一个应用

new-ios-app MyApp
code ~/Projects/ios/MyApp

new-ios-app 会运行 xtool new，设置 bundle ID，添加 VS Code 配置 （.vscode/），设置热重载，为编码代理写入 AGENTS.md， 扩展 .gitignore（签名文件、缓存）并进行首次 git 提交。 选项：--prefix com.other、--dir ~/elsewhere、--no-live（无热 重载）。

运行它：按 F6（或 Ctrl+Shift+B，或使用 Omarchy 按键时的 SUPER+R）， 或在应用文件夹中的终端里：

ios-run --live      # or plain: ios-run

会发生什么：

1. 如果应用已在手机上打开，会先将其关闭（iOS 不会 替换正在运行的应用，安装会一直等待）。
2. xtool 会构建、签名并安装它。
3. 它会在手机上打开，其 print() 输出会以 [app] … 行的形式流式传输到 终端（Ctrl+C 停止监视；应用会继续运行）。

编译错误会显示在 VS Code 的 Problems 标签页中，可点击。

手机重启后的第一次，ios-run 还不能关闭或打开应用：这需要将 开发者磁盘映像 挂载到手机上。运行一次 ios-run-dev（第 6 节）；它会挂载它，并且会一直保持挂载状态，直到手机重启。ios-run 会在出现这种情况时告诉你。

6. 调试

在 VS Code 中：按 F5（或 Ctrl+Alt+D；SUPER+SHIFT+R）。在装订线中点击以设置断点；你会获得变量和调用堆栈窗格、单步执行，以及调试控制台中的 print() 输出。Shift+F5 停止；应用继续运行。

在终端中：

ios-run-dev                          # run under lldb; the app starts right away
ios-run-dev -b ContentView.swift:12  # stop at that line (repeat -b; a function name works too)
ios-run-dev --pause                  # stop at launch, set breakpoints by hand, then `c`
ios-run-dev --attach                 # attach to the app that's already running

在 lldb 中：Ctrl+C 暂停应用，Ctrl+D 退出 lldb（应用继续运行），然后在提示符处按 Enter 会使用相同选项再次构建并运行。

在每个 iOS 版本上的首次调试运行会复制手机的系统库缓存（约 6 GB）并从中提取调试符号，一次需要几分钟。之后就不再需要原始副本：可以从 ~/.cache/omarchy-apple-dev/DeviceSupport/<version>/dsc 中删除它（如果以后需要，它会自动再次复制）。

SwiftUI 仅在应用位于屏幕上时运行视图的 body：当你期望在 UI 代码中命中断点时，请保持手机解锁并打开应用。

7. 热重载

保存一个 .swift 文件，更改会在约 0.7 秒内出现在正在运行的应用中，无需重新安装，并且应用会保持其状态（列表、文本、点击）。运行键会在为其设置好的应用中自动使用它（所有由 new-ios-app 制作的应用）。

7.1 一次性：签名身份

每次交换都是一个小型库，iOS 只有在它由你的开发证书签名时才会加载它，而 xtool 已经用它来为你的应用签名。在你登录（3.6）并安装一个应用后，运行 你自己：

~/.local/share/ios-run/hot-reload/extract-dev-identity.py

它会将 xtool 的证书和私钥复制到 ~/.config/omarchy-apple-dev/development/（仅所有者可访问），并只打印证书的名称和到期时间。你的 Apple 账户中不会创建任何新内容。证书续期后请再次运行它。

7.2 每个视图两行

每个应实时更新的 SwiftUI 视图都需要：

import HotReload

struct ContentView: View {
    @ObserveHotReload private var hotReload   // re-run body after each swap

    var body: some View {
        VStack { /* ... */ }
        .padding()
        .hotReloadable()                      // always the last modifier
    }
}

new-ios-app 的起始视图已经有了它们。它们在 release 和 TestFlight 构建中不会编译出任何内容。

7.3 什么会交换，什么会重新运行

每个文件一个类型。交换会携带被编辑文件中声明的每个类型自己的副本。将每个视图和每个模型放在各自的文件中，否则对旧值的 is/as? 检查可能会失败，并且该文件中的子视图可能会丢失其状态。

保持手机解锁并打开应用。iOS 会暂停后台应用；此时交换会等待，终端会在 5 秒后说明这一点。应用再次回到前台的那一刻它就会加载。

工作原理、其限制和每一项检查：docs/HOW-IT-WORKS.md。

7.4 向现有应用添加热重载

cd ~/Projects/ios/OldApp
/usr/bin/python3 ~/.local/share/ios-run/hot-reload/enable-in-package.py

这会添加 HotReload 包以及仅用于调试的链接标志 (-Xlinker -interposable) 到 Package.swift。然后向每个视图添加两行 (7.2)，并从新应用（或从 ~/.local/share/ios-run/vscode/ 和 templates/）复制 .vscode/ 和 AGENTS.md。

8. 日常使用速查表

* SUPER 键需要可选的 Omarchy 键（安装步骤 4）。F6 和 SUPER+R 仅在 iOS 项目中生效（它们的 .vscode/settings.json 中有 "iosRun.project": true）；在其他地方，F6 照常移动焦点，SUPER+R 照常打开最近 文件。

9. 编码代理（AGENTS.md）

每个应用都会获得一个 AGENTS.md，这是大多数编码代理 都会读取的共享指令文件（Codex、Cursor、GitHub Copilot、Gemini CLI……），其中包含 此设置的规则：如何运行和调试、每个视图都需要的两行热重载、 每个文件一种类型，以及哪些内容不要改动。一行 CLAUDE.md（@AGENTS.md） 让 Claude Code 读取同一个文件。因此无论你使用哪个代理，它都会遵循 相同的规则，并且不会"清理"热重载行。

安装程序还可以为 Claude Code (~/.claude/CLAUDE.md) 和 Codex (~/.codex/AGENTS.md) 添加一个简短的机器级指针，指向这些文档。

10. 保持其正常工作

10.1 Swift 更新（warning: swift-bin: ignoring package upgrade）

ios-toolchain-upgrade            # status: versions, Xcode match, patches, SDK
ios-toolchain-upgrade --upgrade  # minor update (same Swift x.y): upgrade + re-register SDK + patches

主版本更新（例如 Swift 6.4 → 6.5）需要先安装匹配的 Xcode： git pull omarchy-apple-dev（查看其版本表），下载该 Xcode .xip，然后 XCODE_XIP=/path/to/Xcode_NN.xip ios-toolchain-upgrade --upgrade。

每次重新安装 swift-bin 都会重置这三个 .xcspec 补丁： ios-toolchain-upgrade --patch 会将它们恢复（升级会为你完成此操作）。

小心重新运行 omarchy-apple-dev 的 完整 安装程序：它会运行 yay -S swift-bin，这可能会绕过 hold。install-toolchain.sh --repair 是安全的。

10.2 其他事件

11. 故障排除

更多内容及根本原因：docs/HOW-IT-WORKS.md。

12. Intel Mac 和其他机器

这里的一切都在一台 x86_64 Omarchy 机器上测试过，因此运行 Omarchy 的 Intel MacBook 使用相同的软件路径。不同的是硬件，而且我们未测试过：

• USB：iPhone 必须出现在 lsusb（Apple, Inc. iPhone）和 pymobiledevice3 usbmux list 中。在 Intel Mac 上（尤其是带有 T2 芯片的机型），首先检查 USB-C 端口在 Omarchy 下是否能作为数据端口工作。
• 其他所有内容（Swift、SDK、xtool、套件）都是纯软件， 行为应该相同。
• ARM64 Linux：omarchy-apple-dev 报告工具链支持 aarch64； 套件的工具与架构无关，但此组合在此处未测试过。

如果你在其他机器上尝试，最快的端到端检查是： new-ios-app Check，F6（运行），F5（在断点处停止），然后编辑一个 Text 并保存（热重载）。

13. 卸载

rm -f ~/.local/bin/{ios-run,ios-run-dev,new-ios-app,ios-toolchain-upgrade}
rm -rf ~/.local/share/ios-run ~/.config/ios-run

然后，如果你添加了它们：从 ~/.config/hypr/bindings.lua、~/.claude/CLAUDE.md 和 ~/.codex/AGENTS.md 中移除标记的 omarchy-ios-kit 块； 从 ~/.config/Code/User/keybindings.json 中移除套件的条目（旁边有之前的备份）；/etc/systemd/system/usbmuxd.service.d/restart.conf； 以及从 /etc/pacman.conf 中 IgnorePkg 里的 swift-bin。签名身份 副本在 ~/.config/omarchy-apple-dev/development/ 中。已为热重载设置好的应用会保留一个指向 HotReload 包的 .package(path:)：移除它 （以及每个视图的两行代码），即可在不使用套件的情况下构建它们。

14. 致谢和许可

• omarchy-apple-dev 由 Joshua Warren 开发（MIT）：工具链安装程序、device-run.sh、 ship.sh，以及它所基于的发现。
• xtool：基于 SwiftPM 的 iOS 应用构建和 签名，无需 Xcode。
• pymobiledevice3：与 iPhone 通信（安装、启动、调试服务器、文件传输）。
• apple-codesign / rcodesign 和 ipsw：签名和调试符号。
• 热重载方法（可插入链接、重绑定、AnyView 擦除）遵循 InjectionIII， 为 Linux 和真实设备重新实现。

本套件：MIT 许可证，见 LICENSE。