iOS Development Bridge(idb)完全指南:iOS 模拟器与真机自动化 CLI 的安装、使用与源码构建
iOS Development Bridge(idb)完全指南:iOS 模拟器与真机自动化 CLI 的安装、使用与源码构建
导读:
idb(iOS Development Bridge)是开源的 iOS 模拟器与真机自动化命令行工具,由运行在 macOS 上的 Swift "companion" 与可运行在任意平台的 Python 客户端组成。本文以仓库根目录的 README.md 为骨架,结合仓库内 CLI 源码、gRPC 协议定义与构建脚本,系统讲解 idb 的设计理念、安装方式、常用命令、源码构建流程与依赖管理机制,读者可据此快速上手并在自己的测试/数据中心场景中落地使用。
一、idb 是什么:三大设计原则
idb 全称 iOS Development Bridge,是一个用于自动化 iOS Simulators 与 Devices 的命令行接口。与 Xcode 自带的工具链相比,它围绕三条核心原则设计:
- 远程自动化(Remote Automation):
idb由运行在 macOS 上的 "companion" 和可以运行在任何位置的 Python 客户端组成。这使得"设备实验室(Device Lab)"可以部署在数据中心内,也可以将测试执行分片(shard)扇出到一大池 iOS 模拟器上。 - 简单原语(Simple Primitives):
idb暴露细粒度的命令,让复杂工作流可以组合在它们之上。既可以从 IDE 使用,也可以构建默认工具链做不到的自动化测试场景。所有原语在 iOS 版本之间、在模拟器与真机之间都力求行为一致,并通过 CLI 暴露,方便人类与自动化同时使用。 - 暴露缺失功能(Exposing missing functionality):Xcode 有大量功能只能在其图形界面内使用。
idb借力于 Xcode 使用的多个 Private Frameworks,让这些功能可以在无 GUI 的自动化场景中调用。
从仓库结构看,idb 构建在 FBSimulatorControl 与 FBDeviceControl 两个 macOS Framework 之上,二者均包含在本仓库中,也可以脱离 idb 独立使用。idb 正逐步向纯 Swift 代码库迁移:companion 已用 Swift 编写,Frameworks 也在从 Objective-C 迁移。这一迁移的当前状态可以查阅 架构文档,其中说明了:companion 及其 gRPC 服务器基于 grpc-swift 与 SwiftNIO 实现;FBControlCore、FBSimulatorControl、FBDeviceControl、FBXCTestCore 是 Objective-C 与 Swift 的混合体;而 idb-repl 等新组件是纯 Swift 的,其整个依赖闭包不含 Objective-C,因而可以用 Swift Package Manager 构建甚至交叉编译到 Linux(参见 Package.swift 的说明)。
二、系统架构:Python 客户端 + macOS Companion
idb 由两大组件构成,二者缺一不可:
[ idb cli(Python,任意平台) ] <-- gRPC(TCP 或 Unix Domain Socket)--> [ idb_companion(Swift,macOS) ]
|
+---------------------+
| iOS Simulator / Device |
- idb cli:Python 3 编写的命令行客户端,暴露
idb的全部功能。由于是 Python 编写,它不需要运行在连接着 iPhone 或 iOS 模拟器的那台 Mac 上。CLI 本质上是idb_companion的一个瘦客户端封装,所有与 companion 的通信都通过 gRPC 完成,传输层可以是 TCP 或 Unix Domain Socket(详见 架构文档)。该客户端库也可以作为 Python 模块被导入到你自己的代码中。 - idb_companion:Swift 编写的 gRPC 服务器,运行在 macOS 上,直接对接自动化模拟器与真机的原生 API,链接
FBSimulatorControl与FBDeviceControlFramework。一个 companion 进程服务于单个 iOS 目标(一台设备或一个模拟器)。此外,companion 还有一些刻意不开放给 Python CLI 的命令,它们与 iOS 设备管理或模拟器生命周期相关。
从 proto/idb.proto 中的 CompanionService 定义可以看到完整的 RPC 服务面,主要分为以下几类:
- Management:
connect、debugserver、dap、describe、install、instruments_run、log、xctrace_record - Interaction:
accessibility_info、accessibility_action、focus、get_orientation/set_orientation、hinge_angle、hid、open_url、set_location、send_notification、simulate_memory_warning - Settings:
approve、revoke、clear_keychain、contacts_update、photos_clear、setting - App:
launch、list_apps、terminate、uninstall - Video/Audio:
add_media、record、screenshot、video_stream - Crash / xctest / File:
crash_delete、crash_list、crash_show、xctest_run、repl、ls、mkdir、mv、rm、pull、push、tail
在连接模式上,CLI 默认有两种工作方式(见 架构文档 的 Connections 一节):
- 当 CLI 运行在 macOS 上时,会自动为连接到 Mac 的所有目标启动/停止 companion,可以直接对所有模拟器和已连接设备执行命令;
- 当 CLI 运行在其他操作系统上时,不会代为管理 companion,需要显式通过
idb connect附加 companion,或在每次调用时用IDB_COMPANION=hostname:port环境变量指定——这两者在 macOS 上同样可用。
三、快速开始:安装 companion 与 client
idb 的两个组件都由同一个 brew formula 安装,也可以分别安装。
3.1 安装 idb companion
每个目标(模拟器/设备)都会附加一个 companion 进程,供 idb 远程通信。companion 可通过 brew 安装,或从源码构建(参见下文"从源码构建"一节):
brew install facebook/fb/idb
要安装某个特定 release,或任何 commit / pull request 的 CI 构建,可以从仓库检出目录运行 ./homebrew.py。这个脚本(源码位于 homebrew.py)支持以下用法:
./homebrew.py builds # 列出 releases 以及 main 分支最近的 CI 构建
./homebrew.py install v1.6.2 # 安装某个 release
./homebrew.py install 1a2b3c4 # 安装某个 commit 的 CI 构建
./homebrew.py install pr:123 # 安装某个 pull request 的 head 构建
./homebrew.py install run:456 # 安装某次 CI run 的构建
./homebrew.py status # 查看当前安装的是哪个构建
./homebrew.py uninstall --restore # 恢复回 facebook/fb/idb 的 formula
./homebrew.py # 交互式选择器
从脚本头部的文档注释可以看到:构建会安装到本地 tap(idb-local/builds),每次安装都会替换对应的 formula,facebook/fb tap 不会被修改;下载 CI 产物需要 GitHub token(GITHUB_TOKEN 或 GH_TOKEN,或已登录的 gh);脚本仅依赖标准库,要求 Python 3.9 及以上。
3.2 安装 idb client
CLI 工具与 Python 客户端随上面的 brew formula 一并安装,也可以单独通过 pip 安装(release 会发布到 PyPI):
pip3 install fb-idb
注意:idb 客户端要求已安装 Python 3.10 或更高版本。
从源码看,CLI 入口位于 idb/cli/main.py,它通过 build_command_graph 构造完整的命令树(见 idb/cli/command_tree.py),支持运行时扩展命令加载、异常到退出码的映射、以及退出前协程排空等机制。全局参数包括:
--log:设置日志级别(DEBUG/INFO/WARNING/ERROR/CRITICAL,默认 WARNING)--compression:传输压缩算法,默认 GZIP--companion HOSTNAME:PORT:指定要连接的 companion,也可用IDB_COMPANION环境变量--companion-path:companion 二进制路径(仅 macOS 上有效)--companion-tls:强制使用 TLS 加密连接,也可用IDB_COMPANION_TLS环境变量--no-prune-dead-companion:companion 无响应时不修改本地状态- 目标的 UDID 既可作为位置参数,也可用
IDB_UDID环境变量提供(见 target.py 中UDIDTargetedCompanionCommand的实现)
3.3 全局环境变量速查
| 环境变量 | 作用 |
|---|---|
IDB_COMPANION |
指定 companion 的 HOSTNAME:PORT,等价于 --companion |
IDB_COMPANION_TLS |
强制 TLS 加密连接,等价于 --companion-tls |
IDB_UDID |
提供目标 UDID,免去每条命令传入位置参数 |
IDB_* |
启动应用时,任何 IDB_ 前缀的环境变量会被去掉前缀后传递给应用进程 |
四、上手三个核心命令
安装完成后,即可开始探索。以下命令均可在本仓库的 idb/cli/commands 目录中找到对应实现。
4.1 idb list-targets:列出系统上所有目标
该命令会展示你系统上安装的所有模拟器,以及已连接的设备:
$ idb list-targets
...
iPhone 16 | 569C0F94-5D53-40D2-AF8F-F4AA5BAA7D5E | Shutdown | simulator | iOS 26.0 | arm64 | No Companion Connected
iPhone 17 | 2A1C6A5A-0C67-46FD-B3F5-3CB42FFB38B5 | Shutdown | simulator | iOS 26.0 | arm64 | No Companion Connected
iPhone 17 Pro | D3CF178F-EF61-4CD3-BB3B-F5ECAD246310 | Shutdown | simulator | iOS 26.0 | arm64 | No Companion Connected
iPhone Air | 74064851-4B98-473A-8110-225202BB86F6 | Shutdown | simulator | iOS 26.0 | arm64 | No Companion Connected
...
实现上,TargetListCommand(见 target.py)支持 --only 参数按设备类型(device/simulator/mac)过滤以加快查询,也支持 --json 输出机器可读的结果;空结果时输出 No available targets。
4.2 idb list-apps --udid:列出模拟器内已安装的应用
$ idb list-apps --udid 74064851-4B98-473A-8110-225202BB86F6
com.apple.Maps | Maps | system | arm64 | Not running | Not Debuggable
com.apple.MobileSMS | MobileSMS | system | arm64 | Not running | Not Debuggable
com.apple.mobileslideshow | MobileSlideShow | system | arm64 | Not running | Not Debuggable
com.apple.mobilesafari | MobileSafari | system | arm64 | Not running | Not Debuggable
输出列依次为:Bundle ID、应用名称、安装类型(system/user)、架构、运行状态、是否可调试。对应实现为 app.py 中的 AppListCommand。
4.3 idb launch:启动应用
$ idb launch com.apple.mobilesafari
launch 是体现"简单原语"理念的典型命令(见 launch.py),它支持丰富的可选参数:
-d, --wait-for-debugger:应用启动后立即挂起,便于附加调试器(如 lldb)-f, --foreground-if-running:如果应用已在运行,则将其前置-w, --wait-for:等待进程退出,并实时输出应用的全部日志-p, --pid-file:将启动应用的 pid 写入指定文件--enable-repl:以启用 REPL 的方式启动应用(仅模拟器目标),让idb-repl可以附加- 位置参数
app_arguments:传给应用的启动参数 - 环境变量传递:任何
IDB_X形式的环境变量会去掉IDB_前缀后传入应用
五、命令体系一览:简单原语的完整集合
idb 的价值在于命令的粒度与覆盖面。基于 command_tree.py 中声明的命令与 idb/cli/commands 目录,可以归纳出如下功能族:
| 功能族 | 代表命令 | 源码 |
|---|---|---|
| 目标管理 | connect、disconnect、list-targets、create、boot、shutdown、erase、clone、delete、delete-all、describe |
target.py |
| 应用管理 | install、uninstall、terminate、list-apps |
app.py |
| 日志 | log(支持 --system/--process/--predicate/--style 等 log stream 风格参数) |
log.py |
| 截图/视频 | screenshot、record、video-stream |
screenshot.py |
| XCTest | xctest install、xctest list、xctest list-bundle、xctest run |
xctest.py |
| 文件操作 | fs-pull、fs-push、ls、mkdir、mv、rm、tail |
file.py |
| 交互模拟 | hid、tap、accessibility、ui、focus |
hid.py 等 |
| 系统设置 | approve、revoke、settings、keychain、contacts、photos、notification、location、rotation、media |
approve.py 等 |
| 调试 | debugserver、dap、crash、xctrace、instruments |
debugserver.py 等 |
值得一提的细节:idb log 透传 log stream 风格的参数(如 --predicate 'eventMessage contains "my message"'、--style json),通过 idb log -- --style json 的形式调用(见 log.py)。idb screenshot 支持 --format(默认 png)、--compression-quality、--crop X,Y,WIDTH,HEIGHT、--scale-factor 等参数,目标路径写 - 则输出到 stdout(见 screenshot.py)。
在开发约定上,.github/CONTRIBUTING.md 明确了:凡是长生命周期(如 instruments)、产生增量输出(如 log)、或在客户端/服务器之间推送大量数据的 RPC,都应使用 gRPC 流式调用,以保证 idb 的响应性与性能——这与 proto/idb.proto 中大量 stream 双向流方法的设计相互印证。
六、从源码构建 idb
6.1 前置条件
- macOS 15+,且安装 Xcode 26.0+
- XcodeGen:
brew install xcodegen - 构建
idb_companion还需要 protobuf 编译器:
brew install protobuf
注意:build.sh 会自行构建两个 Swift 代码生成插件(protoc-gen-swift 与 protoc-gen-grpc-swift-2),版本与 revision 取自 Package.resolved,从而保证生成的代码与运行时版本一致。
6.2 构建命令
仓库根目录的 build.sh 是唯一构建入口:
# 构建所有目标并组装可运行的发行包
./build.sh build
# 或只构建一个子集:frameworks、shims、idb_companion,或某个具体 framework
./build.sh build frameworks
./build.sh build idb_companion
./build.sh build FBControlCore
# 查看全部选项
./build.sh help
从 build.sh 的 usage 文档(build.sh)可以看到完整的目标清单:all、distribution、frameworks、idb_companion、idb-repl、sim-video、shims、fixtures,以及 FBControlCore、FBDeviceControl、FBSimulatorControl、FBSimulatorXCTest 等 framework 目标和 Shimulator-iOS、Shimulator-macOS、Repl-iOS、Repl-macOS、ReplHost、SimulatorFrameworkBridge-iOS、SimulatorFrameworkBridge-tvOS 等细分产物。
构建产物分别写入 Build/Products 下:macOS 产物在 Build/Products/Release,模拟器产物在平台特定的 Release-* 目录。framework 目标是静态库并被链接进可执行文件,因此不会复制进运行时发行包。完整的 ./build.sh build 会组装出自包含的发行包 Build/Distribution:
Build/Distribution/
idb_companion # the companion executable
idb-repl # the REPL client
sim-video # the simulator video recorder
*.bundle # SwiftPM resource bundles, when present
Resources/
Swift/ # Swift back-deployment libraries
libShimulator-iOS.dylib
libShimulator-macOS.dylib
libRepl-iOS.dylib
libRepl-macOS.dylib
SimulatorFrameworkBridge-iOS
SimulatorFrameworkBridge-tvOS
ReplHost.app
IDBAPI.swiftinterface
重要:可执行文件相对自身位置解析捆绑的运行时依赖,因此拷贝或迁移时请保持 Build/Distribution 目录整体完整。build_distribution 的实现见 build.sh,它会先校验必需产物是否齐备,再把 shims、guest 二进制、ReplHost.app、Swift 回部署库等复制到正确位置。
从构建脚本内部还可以看到几个工程化细节:build.sh 必须从 idb 源码根目录运行(会校验 Package.swift 与 Companion/project.yml 是否存在);在文件系统不支持 xattr(如 EdenFS)时会自动改用外部构建目录并通过符号链接保持 Companion/project.yml 中硬编码的 ../Build/Products/Release/... 引用可解析(build.sh);每次 xcodebuild 调用都会保留完整原始日志于 Build/Logs/xcodebuild,失败时自动回读关键诊断(build.sh);构建默认仅产出 arm64 切片并显式设置 ENABLE_USER_SCRIPT_SANDBOXING=NO、CLANG_ENABLE_EXPLICIT_MODULES=NO 等(build.sh)。
6.3 运行测试
# 运行全部测试
./build.sh test
# 测试特定 framework
./build.sh test FBSimulatorControl
更细粒度地,可以单独运行 FBSimulatorControl 的某一套测试套件(build.sh):
./build.sh test FBSimulatorControlUnitTests # 单元测试,无需模拟器
./build.sh test FBSimulatorControlBootTests # 启动生命周期测试,会创建并启动一个模拟器
./build.sh test FBSimulatorControlSmokeTests # 冒烟测试,从环境获取已启动的模拟器
测试执行启用了超时控制:默认单测执行时间额度 60 秒、最大 600 秒,挂死的测试会在大约一分钟内变成具名失败(build.sh)。FBSimulatorControl 的测试包会先构建 shims 与 accessibility bridge 作为资源,FBXCTestCore 的测试包会先构建 fixtures。
6.4 重新生成 Xcode 工程与 gRPC 代码
Xcode 工程文件由 XcodeGen 依据 project.yml 生成。不构建、仅重新生成工程:
./build.sh generate
该命令会依次生成 FBSimulatorControl、Shimulator、Repl、SimulatorFrameworkBridge、ReplHost、Fixtures 与 idb_companion 等工程的 .xcodeproj(见 build.sh)。generate-proto 则从 proto/idb.proto 重新生成 gRPC Swift 代码(build.sh),生成位置为 IDBGRPCSwift/。由于 Companion/project.yml 通过 glob 展开源文件,代码生成必须先于工程生成。
七、Swift 迁移与依赖管理
idb 正在向纯 Swift 迁移,这带来了一套严格的依赖锁定机制:
- Package.resolved 是运行时与两个 Swift 代码生成插件的共享锁文件,Package.swift 与 Companion/project.yml 中的版本必须与之一致。
build.sh会把锁文件暂存进生成的 Xcode workspace 并禁用自动包解析;每次插件构建与 Xcode 构建之后都会校验 resolved 的版本、revision 与仓库地址(build.sh)。- 代码生成使用
Build/Codegen下的增量 SwiftPM 构建,即使插件二进制已缓存,每次构建也会重新校验锁,并在 XcodeGen 展开源码 glob 之前重新生成协议源码——依赖升级不可能静默复用旧的生成代码。 - 仓库内的 CI/dependency_lock.py 实现了锁文件解析与校验逻辑(要求每个 pin 同时具备 40 位 git revision 与语义化版本号)。
在没有 Apple 工具链的环境下,可用以下命令验证依赖守卫:
bash tests/build-test.sh "$PWD"
python3 -m unittest CI.dependency_lock_tests
GitHub CI 会同时运行这两个检查。
八、文档、贡献与许可
- 文档:项目的完整文档(含 guided tour、命令列表、安装与开发说明)位于仓库 website/docs 目录,其中 架构文档 详细描述了组件划分、连接模式、框架概念与纯 Swift 迁移状态。
- 贡献:开发流程约定见 .github/CONTRIBUTING.md:核心功能应下沉到
FBSimulatorControl与FBDeviceControl,companion 只负责在框架数据模型与 gRPC Protocol Buffers 之间做转换;新 API 应使用async throws风格的 Swift 协议;改变 gRPC 接口的 PR 需要同时包含客户端与服务端改动;companion 接口尽量向后兼容旧客户端。 - 许可:
idb采用 MIT 许可,见 LICENSE。
总结
idb 以"远程自动化、简单原语、暴露缺失功能"三大原则,把 iOS 模拟器与真机的自动化能力封装成一套可组合的细粒度命令,并通过 Python CLI + Swift companion 的 gRPC 架构天然支持数据中心式的远程设备池。本文覆盖了从 brew/pip 安装、list-targets/list-apps/launch 等核心命令,到 build.sh 源码构建、homebrew.py 定向安装与 SwiftPM 依赖锁定机制的完整链路。无论你是想在本机快速驱动模拟器,还是想在 CI/设备实验室中大规模编排 iOS 测试,都可以直接依据本文在仓库内找到对应的命令实现与构建依据,进一步深入定制。