iOS Development Bridge(idb)完全指南:iOS 模拟器与真机自动化 CLI 的安装、使用与源码构建

原创2026-10-12 21:44:201,987 阅读
文章标签:开发工具移动开发测试

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 与 FBDeviceControl Framework。一个 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 一节):

  1. 当 CLI 运行在 macOS 上时,会自动为连接到 Mac 的所有目标启动/停止 companion,可以直接对所有模拟器和已连接设备执行命令;
  2. 当 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 测试,都可以直接依据本文在仓库内找到对应的命令实现与构建依据,进一步深入定制。

登录后查看全文
idb