FBDeviceControl 深入解析:idb 如何通过 MobileDevice.framework 自动化 iOS 真机
FBDeviceControl 深入解析:idb 如何通过 MobileDevice.framework 自动化 iOS 真机
FBDeviceControl 是 idb 项目中与 FBSimulatorControl 并行的「姊妹框架」,专门负责 iOS 真机(Device) 的自动化控制。本文将带你完整走通 macOS 上访问 iOS 设备所依赖的私有框架与设备端服务栈(MobileDevice.framework、AMDevice、AMRestorableDevice、AMDServiceConnection、AFC、Developer Disk Images、Instruments 与 Video 编码),并结合 FBDeviceControl/README.md 与仓库源码,给出可直接落地的 idb 命令行实操,包括磁盘镜像挂载与 debugserver 真机调试全流程。
一、FBDeviceControl 在 idb 中的定位
FBDeviceControl 与 FBSimulatorControl 一样,本质上是 idb 的一个实现细节(implementation detail),而 idb 是使用它所实现能力的最简单入口。它也被设计成可以被直接链接:主要面向在进程内嵌入设备自动化能力的原生 macOS 应用,或需要比 idb CLI 更细粒度控制的调用方。
这里有一个明确的取舍原则(README 原文给出的 trade-off):
idbCLI 及其 gRPC 接口是项目的兼容性边界;框架自身的 API 会随实现更自由地变化。
也就是说,外部依赖方应当锚定在 idb CLI / gRPC 层,而不是直接依赖 FBDeviceControl 的内部 API。框架对应的核心实现文件位于 FBDeviceControl/Management/Device.swift,它封装了后文将要介绍的两种设备引用。
二、底层基石:MobileDevice.framework
2.1 什么是 MobileDevice.framework
MobileDevice.framework 是 macOS 的系统私有框架,默认位于:
/System/Library/PrivateFrameworks/MobileDevice.framework/MobileDevice
它是私有框架,Apple 官方不提供任何文档。其 API 绝大多数是 CoreFoundation 风格——纯 C 符号、以 CF 对象作为出入参。也正因为 CF 对象与 Objective-C 之间通常是 Toll-Free Bridged(免费桥接),Swift 也能触达这些 API。FBDeviceControl 本身用 Swift 编写,而 MobileDevice.framework 的调用表被统一声明在一个 C 头文件中:FBDeviceControl/Management/AMDefines.h。
初看时这个框架很难上手(私有 API 通常以 Objective-C 类形式暴露时更容易使用),但 CoreFoundation API 的常见套路在这里同样适用。一个事实侧面印证了它的重要性:
Apple 在 macOS 上凡是与 iOS 设备交互的应用(Finder/iTunes、Xcode、Accessibility Inspector、Apple Configurator 2、Photos)几乎都会用到
MobileDevice.framework。
正是因为有如此庞大的「客户群」,人们才有条件逐一弄清每个 API 调用的输入输出。AMDefines.h 中定义的 AMDCalls 结构体就是 FBDeviceControl 实际用到的全部调用表,从中可以看到典型的分组:
- 连接与会话管理:
Connect、Disconnect、IsPaired、Pair、StartSession、StopSession、ValidatePairing; - 设备属性获取:
CopyDeviceIdentifier、CopyValue(按 domain 读取设备值); - 设备发现:
CreateDeviceList、NotificationSubscribe、NotificationUnsubscribe; - 服务连接:
ServiceConnectionGetSocket、ServiceConnectionSend/Receive、ServiceConnectionSendMessage/ReceiveMessage、ServiceConnectionGetSecureIOContext; - 应用管理:
SecureInstallApplication、SecureUninstallApplication、SecureTransferPath、LookupApplications、CreateHouseArrestService; - 磁盘镜像:
MountImage; - 描述文件(Provisioning Profiles):
CopyProvisioningProfiles、InstallProvisioningProfile、RemoveProvisioningProfile等; - 可恢复设备(Restorable Devices):
RestorableDeviceRegisterForNotifications、RestorableDeviceGetState、RestorableDeviceCopySerialNumber等; - 调试辅助:
InitializeMobileDevice、SetLogLevel、CopyErrorText。
FBDeviceControl 的目标是尽可能使用这些原生 API,把 MobileDevice.framework 视为 macOS 上与 iOS 设备交互的「权威方式」(canonical way)。与之相对的跨平台重实现是 libimobiledevice 等项目(它们在非 macOS 主机上重新实现了同一套语义)。
2.2 与 Xcode 的关系:延迟加载
MobileDevice.framework 并不能覆盖所有 iOS 设备操作,部分功能依赖主机上安装的 Xcode(并完成 xcode-select 指向)。这意味着:
- 部分设备操作在没有 Xcode 的环境下也能完整工作;
- 部分功能则依赖 Xcode 的存在——通常这些功能本来就只能通过 Xcode 获得。
FBDeviceControl 会延迟加载(defer)Xcode 特定功能,直到真正使用它时才加载,从而避免在不需要 Xcode 的场景下失败。典型例子:仅做设备列表(device listing)的主机即使没有 Xcode,列表功能依然可用。
三、设备对象模型:AMDevice 与 AMRestorableDevice
3.1 AMDevice:已启动并已连接的单台设备
AMDevice 是 MobileDevice.framework 定义的 CF 类型,表示一台已连接并已启动(booted)的 iOS 设备。所有相关函数都以 AMDevice 前缀开头,且通常把 AMDevice 作为第一个参数。关键约束:
- 设备必须在 booted 状态且已附着到主机;
- 处于 DFU / Restore 模式的设备不会产生
AMDevice实例。
对 AMDevice 操作的前提是手机「信任」主机——即你熟悉的 iPhone 连接 Mac 时弹出的 「Trust Dialog」(信任对话框)。绝大多数调用在信任交换完成前都会失败。Mac 会在本地维护信任交换所用的加密组件存储,因此同一台 iOS 设备反复连接同一主机时,不会每次都要求重新授权。如果没有这套机制,iOS 设备根本无法用于 Continuous Integration(持续集成)环境。
在仓库中,这一关键组件由 FBDeviceControl/Management/MobileDevice.swift 中的 MobileDevice 类承载。从源码可以看到它是一个 TargetInfo, DeviceCommands 的 Swift 封装,内部持有 AMDCalls 调用表与 amDeviceRef(AMDevice 引用),其 amDeviceRef 的 setter 会手动调用 calls.Retain/Release 来管理 CF 引用计数(因为 AMDevice 的 ownership 走 AMDevice call table 而非 ARC)。
3.2 异步设备发现:为什么列表不可靠
发现设备的过程是异步的,因此「在某个时间点抓取一份 AMDevice 快照列表」是不可靠的做法。FBDeviceControl 不使用快照,而是通过 MobileDevice.framework 的 AMDeviceNotificationSubscribe API 订阅通知——每次设备可用性状态变化时都会收到一个 AMDevice 实例。这正是 FBDeviceControl/Management/AMDeviceManager.swift 的实现方式:
startListening()调用calls.NotificationSubscribe(amDeviceListenerCallback, ...),把 manager 自身作为 context 指针注册;- C 回调
amDeviceListenerCallback根据AMDeviceNotificationType(connected/disconnected/paired/unsubscribed)分发处理; connected/paired时执行amDeviceConnected:连接设备 → 读取 ECID → 尝试配对会话(允许失败,未配对设备仍以降级信息上报)→ 读取设备值 → 注册进设备存储。
Apple 自家基于 MobileDevice.framework 的工具也继承了这一异步特性:xcodebuild 有 -destination-timeout 参数,Apple Configurator 的 cfgutil 有 --timeout 参数,Xcode 的 "Devices and Simulators" 窗口背后同样存在,只是你通常感知不到。
AMDeviceManager 还支持 ECID 过滤(ecidFilter):只有匹配过滤条件的设备才会被接入(见 AMDeviceManager.init(calls:work:asyncQueue:ecidFilter:logger:)),这在多设备 CI 场景下很有用。
3.3 AMRestorableDevice:涵盖 DFU / Restore 的完整视图
AMRestorableDevice 同样是 MobileDevice.framework 的一部分,但它表示任何附着到主机且已通电的 iOS 设备——包括启动中(booting)、已启动(booted)以及 DFU / Restore 模式的设备。
这套 API 极其受限,只用于描述设备以及执行仅与未启动状态相关的操作(例如把一台已启动设备移入/移出 DFU / Restore 状态)。它还能帮助你理解:为什么一台看似已连接的设备可能没有对应的 AMDevice 实例。
正因如此,FBDeviceControl 允许一个统一的 Device 实例同时由 AMDevice 和/或 AMRestorableDevice 背书,从而对已连接的 iOS 设备提供完整可观测性(full observability)。对应的管理实现是 FBDeviceControl/Management/AMRestorableDeviceManager.swift,它通过 RestorableDeviceRegisterForNotifications 订阅连接/断开通知,并用 RestorableDeviceGetState 读取设备状态(AMRestorableDeviceState 枚举定义了 DFU = 0、Recovery = 1、RestoreOS = 2、BootedOS = 4、Unknown = 5)。
从 Device.swift 的源码可以看到这种「双背书」设计:Device 持有 amDeviceStorage 与 restorableDeviceStorage,cacheValues(from:overwrite:) 用 AMDevice 的富信息优先覆盖、用 RestorableDevice 的信息只填补空缺;在 withConnectedDevice / withHouseArrestAFCConnection 等操作中,如果设备没有 AMDevice 背书(例如处于 DFU/Restore),会抛出 AMDeviceServiceError.notAMDeviceBacked 明确失败——对应 README 所述「向处于 DFU/Restore 模式的设备安装应用会正确失败」。
四、AMDServiceConnection:通往 lockdown 服务的传输层
4.1 概念:Transport 而非 Protocol
要在 iOS 设备上做任何事,基本都需要连接到设备上运行的某个 lockdown service(锁定服务)。这类服务数量庞大,例如:
com.apple.syslog_relay:把系统日志从设备转发到主机(你在 Xcode 的 "Simulators and Devices" 窗口里见过它干活);com.apple.screenshotr(截图服务);- SpringBoard 相关服务等。
连接通过 AMDeviceSecureStartService 调用创建,返回 AMDServiceConnection 类型。与之相关的一批函数负责在连接上像操作文件描述符一样收发二进制数据。
必须强调的是:AMDServiceConnection 只是「传输层」,不是「协议层」。每个 lockdown service 都有自己截然不同的二进制协议:简单的如 com.apple.syslog_relay 只是反复发送文本;复杂的如 Instruments 用到的协议则要麻烦得多。不存在一个所有 lockdown service 通用的协议。
4.2 Secure Context:加密传输的关键
AMDServiceConnection 可以携带一个 secure context——在 TLS 连接上发送数据所需的加密信息。这解释了为什么必须使用 AMDServiceConnection(Send|Receive) 系列调用,而不是裸的 read/write 系统调用:在加密传输通道上发送未加密数据,接收方将无法读取。
secure context 的存在可以在运行时通过检查连接值检测出来(对应调用表里的 ServiceConnectionGetSecureIOContext)。在较新的 iOS 版本中,一些服务开始强制要求加密 IO,因此检测并使用这些调用非常重要。仓库实现位于 FBDeviceControl/Services/LockdownServiceConnection.swift:LockdownServiceConnection 在构造时调用 calls.ServiceConnectionGetSecureIOContext(connection) 判断连接是否为 Secure,并以此决定底层是裸传输还是带加密包装的传输。
4.3 Plist 协议:唯一的通用例外
有一个例外:Plist 协议(由 AMDServiceConnection(Send|Receive)Message 调用实现),它在截图服务、SpringBoard 服务等一系列服务间通用。实现位于 LockdownServiceConnection.swift,核心规则是:
发送/接收两侧都是「一个长度头(4 字节大端
UInt32)+ 一段二进制 plist」。
源码中 sendMessage(_:) 调用 ServiceConnectionSendMessage 并以 CFPropertyListFormat.binaryFormat_v1_0 编码;send(withLengthHeader:) 则先写 HeaderIntType(data.count).bigEndian 再写数据。这个文件同时实现了流式读写:发送/接收缓冲均为 4 KB(SendBufferSize/ReadBufferSize = 1024 * 4),并提供了 send(_:)、receive(_:)、receive(_:toFile:)、receiveUp(to:) 以及「读到耗尽为止并喂给 DataConsumer 的 reader」等接口。
五、AFC(Apple File Connection):设备文件操作
AFC 是 MobileDevice.framework 中另一组通用 API,用于在 iOS 设备上进行文件操作。它同样是一个包装在 AMDServiceConnection 传输之上的协议,操作对象是 AFCConnection 类型,提供:读取、写入、列目录、移动、复制、删除文件等函数。仓库中的 Swift 封装是 FBDeviceControl/Services/FileConduit.swift 里的 FileConduit 类(AFCConnectionRef 的对象包装,并定义了 FileConduitError 的完整错误类型)。
一个关键事实是:
在未越狱(non-jailbroken)的设备上,无法获得覆盖整个根文件系统的
AFC连接。取而代之的是对应 iPhone 系统内各个容器/沙盒的不同 lockdown 服务。
典型的 AFC 服务包括:
| AFC 服务 | 用途 |
|---|---|
com.apple.afc |
访问照片/媒体(Photos/Media) |
AMDeviceCreateHouseArrestService |
访问应用沙盒(Application Sandboxes) |
com.apple.crashreportcopymobile |
访问崩溃日志(crash logs) |
在 MobileDevice.swift 中可以看到对应的 withAFCConnection(_:calls:_:) 与 withHouseArrestAFCConnection(forBundleID:afcCalls:_:) 模式:前者把服务连接包装成 FileConduit,后者通过 AMDeviceServiceManager.houseArrestService(forBundleID:) 获取某个 bundle 的沙盒 AFC 连接。源码注释还点明了一个细节:AMDevice 会话(session)与 AFC 连接的生存期不同——session 在服务启动后即被释放(约 60 秒超时),而 AFC 连接会按服务的复用超时(AMDeviceManager.swift 中 serviceReuseTimeout = 6.0 秒)被池化复用,使同一 bundle 的下一次操作能直接复用连接。
六、Developer Disk Images:扩展设备能力的镜像
6.1 为什么需要它
iOS 基础镜像内置了一批 lockdown 服务,但 Xcode 内的许多功能并不来自基础系统的服务。为了向已连接的 macOS 主机提供额外能力,Xcode 随附了 Developer Disk Image(开发者磁盘镜像)(相关工具类见 FBControlCore/Utility/DeveloperDiskImage.swift)。
它本质上是一个普通 .dmg 文件(macOS 可直接打开),镜像内包含若干可执行文件、库和描述 lockdown 服务的 plist;将镜像挂载到设备后,这些服务会被新增到设备上。关键安全约束:
- 不能随便往 iOS 设备上挂载任意磁盘镜像——每个镜像及其二进制都由 Apple 签名,只有具备 Apple 真实签名的镜像才允许挂载;
- 镜像中的服务与 iOS 版本内部的 API 交互,因此 Developer Disk Image 通常随 iOS 大/小版本不同而不同;
- 镜像内含的服务与 Xcode、Instruments、Accessibility Inspector 专属功能相关联,其可用性与协议版本可能随 Xcode 版本变化,客户端实现也会因此存在差异。
FBDeviceControl 对镜像操作(挂载/卸载)的封装在 FBDeviceControl/Commands/DeviceDeveloperDiskImageCommands.swift,底层调用 AMDCalls.MountImage,并通过 com.apple.mobile.mobile_image_mounter 服务收发 CopyDevices / UnmountImage 命令。镜像搜索路径为 Xcode 的 Platforms/iPhoneOS.platform/DeviceSupport 目录(每个版本子目录下包含 DeveloperDiskImage.dmg 与 DeveloperDiskImage.dmg.signature),也支持通过环境变量 IDB_EXTRA_DEVICE_SUPPORT_DIR 追加额外镜像目录(见 DeveloperDiskImage.swift 中 InstalledDeveloperDiskImages 的实现)。
镜像匹配采用「就近选择」策略:bestImage(forImages:targetVersion:logger:) 依据 scoreVersions(major 差 × 10 + minor 差)打分排序;只有当最佳镜像的 major 版本与设备一致(minor 尽可能接近)时才算合适,否则抛出 noSuitableImage。
6.2 自动挂载与手动管理
任何依赖 Developer Disk Image 服务的 FBDeviceControl 功能,都会隐式地为当前设备搜索并挂载最合适的镜像(对应 ensureMounted():读取设备 productVersion → 匹配镜像 → 挂载;若相同签名镜像已挂载则跳过,见 DeviceDeveloperDiskImageCommands.swift 的 mountDeveloperDiskImage)。
同时,idb 也通过文件命令的 "disk image container" 提供了手动管理挂载的方式(见 idb/cli/commands/file.py 中 FileContainerType.DISK_IMAGES 的定义)。README 给出的完整操作如下:
# 列出当前 Xcode 内所有可用镜像,以及当前已挂载的镜像(如有)。
# 未挂载任何镜像时,mounted 路径为空。
$ idb file ls --disk-images .
15.0/DeveloperDiskImage.dmg
12.1/DeveloperDiskImage.dmg
10.0/DeveloperDiskImage.dmg
9.2/DeveloperDiskImage.dmg
9.1/DeveloperDiskImage.dmg
14.2/DeveloperDiskImage.dmg
13.4/DeveloperDiskImage.dmg
11.3/DeveloperDiskImage.dmg
13.0/DeveloperDiskImage.dmg
12.2/DeveloperDiskImage.dmg
10.1/DeveloperDiskImage.dmg
13.1/DeveloperDiskImage.dmg
11.0/DeveloperDiskImage.dmg
14.3/DeveloperDiskImage.dmg
13.5/DeveloperDiskImage.dmg
11.4/DeveloperDiskImage.dmg
12.3/DeveloperDiskImage.dmg
10.2/DeveloperDiskImage.dmg
14.0/DeveloperDiskImage.dmg
13.2/DeveloperDiskImage.dmg
11.1/DeveloperDiskImage.dmg
14.4/DeveloperDiskImage.dmg
13.6/DeveloperDiskImage.dmg
12.0/DeveloperDiskImage.dmg
14.5/DeveloperDiskImage.dmg
12.4/DeveloperDiskImage.dmg
10.3/DeveloperDiskImage.dmg
14.1/DeveloperDiskImage.dmg
11.2/DeveloperDiskImage.dmg
13.3/DeveloperDiskImage.dmg
9.0/DeveloperDiskImage.dmg
9.3/DeveloperDiskImage.dmg
13.7/DeveloperDiskImage.dmg
$ idb file ls --disk-images mounted
# 为当前已连接设备(iOS 15.0)的 iOS 版本挂载对应镜像(15.0 成功)
$ idb file mv --disk-images 15.0/DeveloperDiskImage.dmg mounted
# 现在可以看到镜像已挂载
$ idb file ls --disk-images mounted
15.0/DeveloperDiskImage.dmg
# 通过 rm 卸载镜像。镜像在主机上保持完整,仅从设备上卸载。
$ idb file rm --disk-images mounted/15.0/DeveloperDiskImage.dmg
$ idb file ls --disk-images mounted
可以看到,磁盘镜像被建模为一个「文件容器」,对它的挂载/卸载操作被复用为 file ls / file mv / file rm 这几个熟悉命令,上手成本很低。
七、Instruments Service:启动与性能剖析的关键
Instruments Service 是 Developer Disk Image 内的一个服务,对 iOS 设备自动化极其重要。Instruments.app 与 instruments 命令行提供了大量用于启动、剖析应用和 iOS 设备的功能,因此它也是**应用启动(app launching)与进程列表(process listing)**等任务的必要组成部分。
该协议的客户端实现由 Apple 的 DTXConnectionServices 提供,FBDeviceControl 内有一个临时性的重实现:FBDeviceControl/Services/InstrumentsClient.swift。源码注释说明其对 DTXMessage 协议的理解参考了社区项目 ios_instruments_client,并给出了协议细节:32 字节的 DTXMessageHeader(magic = 0x1F3D5B79、cb、fragmentId、fragmentCount、length、identifier、conversationIndex、channelCode、expectsReply)加上 16 字节的 DTXMessagePayloadHeader(flags、auxiliaryLength、totalLength)。由于 Swift 不保证结构体内存布局与 C 一致,编解码都是按字段声明顺序逐字段进行的,而不是直接拷贝结构体内存。
对应的命令层封装在 FBDeviceControl/Commands/DeviceInstrumentsCommands.swift。
八、视频编码:把 iPhone 屏幕流到主机
FBDeviceControl 的关键特性之一是通过 USB 把 iPhone 屏幕实时流转发到主机——你也许在 QuickTime 的 "Screen Recording" 功能里见过它(把已连接 iOS 设备的视频录制成 Mac 上的 .mp4)。
8.1 基于 AVFoundation 的采集链
该能力的接入是通过 AVFoundation 以「Capture Device(采集设备)」形式提供的,核心实现位于 FBDeviceControl/Video/DeviceVideo.swift。整个链条如下(源码可见):
allowAccessToScreenCaptureDevices():通过 CoreMediaIO 设置kCMIOHardwarePropertyAllowScreenCaptureDevices,允许使用屏幕采集设备——在较新的 macOS 上,使用 Capture Device 还要求宿主进程(使用FBDeviceControl的进程)具备系统级权限;findCaptureDevice(for:):以设备udid轮询查找对应的AVCaptureDevice(带超时);captureSession(for:):创建AVCaptureSession并添加AVCaptureDeviceInput;video(for:filePath:):用VideoFileWriter(来自 FBVideoCore)把 session 与目标文件绑定。
拿到 iOS 设备屏幕的 Capture Device 后,就可以建立 Capture Session 并按消费者最需要的帧格式配置。FBDeviceControl 从设备接收帧样本,这些样本在被转发到数据流之前可以选择性重新编码。
8.2 两种输出形态
FBDeviceControl 支持两种输出:
- 写入
.mp4视频文件; - 输出为编码后的数据流(stream of encoded data)——这类流可以转交给其他应用,用于 webRTC、HTTP Live-Streaming 等场景。
视频录制与流式输出的命令层分别位于 FBDeviceControl/Commands/DeviceVideoRecordingCommands.swift 与 FBDeviceControl/Commands/DeviceVideoStreamCommands.swift。
九、调试应用:debugserver 真机调试全流程
idb(经由 FBDeviceControl)支持在 iOS 设备上启动 debugserver,从而不经过 Xcode 调试真机 App。在动手之前,先明确 iOS 允许的边界(README 列出的三条硬性约束):
- 只能用
lldb作为调试器客户端; - 只能调试「Developer Signed」签名应用——调试 Enterprise 签名或 App Store 应用不受支持,iOS 也不允许;
- 不支持/不允许附加(attach)到已启动的应用——被调试应用必须由调试器启动。
9.1 与普通调试的差异:只有「如何开始」不同
真机调试不像 lldb 一行命令那么简单,但变化的只有启动调试会话的方式。设备上的完整流程如下:
- 把要调试的应用安装到 iOS 设备,同时在主机上保存一份应用副本——主机副本是
lldb对调试应用内符号做 symbolication(符号化) 所必需的; - 挂载当前设备对应的 Developer Disk Image——因为
debugserverlockdown 服务就包含在镜像内(见 DeviceDebugServerCommands.swift 的connect():先device.developerDiskImage.ensureMounted()再启动服务); - 通过 lockdown 启动
debugserver服务(实现见 FBDeviceControl/Commands/DeviceDebugServerCommands.swift),得到一个lldb可与之通信的双向 socket 流——这是一个使用 gdb 协议的远程调试服务器; - 把
debugserver服务包装进一个 socket 暴露到进程外,使其可被外部连接; - 启动
lldb,通过暴露的 socket 连上debugserver,并下发一系列命令让lldb知道如何连接、如何会话; - 现在
lldb就可以启动并调试应用了。
源码补充了服务名的选择细节:connect() 会根据镜像对应的 Xcode 主版本选择服务名——Xcode 12 及以上用 com.apple.debugserver.DVTSecureSocketProxy,更早版本用 com.apple.debugserver;launch(forHostApplication:port:) 还会检查设备系统版本,iOS 17 及以上直接抛出不支持错误(DeviceDebugServerError.unsupportedOSVersion,见 DeviceDebugServerCommands.swift 第 66-68 行)。
9.2 制作一个 "debuggable app"
除了前面提到的「必须 Developer Signed」,还有一个约束:主机上必须持久保存一份应用副本(供 lldb 做符号化)。
idb 通过 idb install 的 --make-debuggable 参数完成这件事(参数定义见 idb/cli/commands/app.py):
# 安装应用,同时持久化到磁盘,以便后续启动 debugserver 时 idb 能找到它
$ idb install --make-debuggable /path/to/SomeApp.app
安装后可以在 idb list-apps 的输出中确认应用是否可调试:
$ idb list-apps | grep SomeApp
com.foo.SomeApp | SomeApp | user_development | no archs available | Unknown | Debuggable | pid=None
输出中的 Debuggable 标记即代表该应用已具备可调试条件,可以对其启动 debugserver。
9.3 启动 debugserver
对任意「Debuggable」应用,用 idb debugserver 命令启动(CLI 实现见 idb/cli/commands/debugserver.py,包含 start / stop / status 三个子命令):
# 启动 debugserver,stdout 会返回一列引导(bootstrapping)命令
$ idb debugserver start com.foo.SomeApp
platform select remote-ios --sysroot '/Users/Someone/Library/Developer/Xcode/iOS DeviceSupport/15.2.1 (19C63) arm64e/Symbols'
target create '/private/tmp/idb-applications/com.foo.SomeApp/SomeApp.app'
script lldb.target.modules[0].SetPlatformFileSpec(lldb.SBFileSpec("/private/var/containers/Bundle/Application/64B4DDB3-1049-458C-AA0B-F56AF4DCF0E0/SomeApp.app"))
process connect connect://localhost:10881
从 DeviceDebugServerCommands.swift 的 lldbBootstrapCommands(forApplicationAtPath:port:) 可以看到这四条命令的生成逻辑:platform select remote-ios --sysroot …(用设备的 build version 去匹配 Xcode 的 DeviceSupport Symbols 目录,找不到时降级为不带 --sysroot)、target create '<host 应用路径>'、script lldb.target.modules[0].SetPlatformFileSpec(...)(把宿主上的目标与设备端真实安装路径绑定)、process connect connect://localhost:<port>。
返回的引导命令可用于初始化 lldb 调试会话。
9.4 通过 lldb 完成引导
# 启动 lldb 并依次执行上面的引导命令
$ lldb
(lldb) platform select remote-ios --sysroot '/Users/Someone/Library/Developer/Xcode/iOS DeviceSupport/15.2.1 (19C63) arm64e/Symbols'
Platform: remote-ios
Connected: no
SDK Path: "/Users/Someone/Library/Developer/Xcode/iOS DeviceSupport/15.2.1 (19C63) arm64e/Symbols"
(lldb) target create '/private/tmp/idb-applications/com.foo.SomeApp/SomeApp.app'
script lldb.target.modules[0].SetPlatformFileSpec(lldb.SBFileSpec("/private/var/containers/Bundle/Application/64B4DDB3-1049-458C-AA0B-F56AF4DCF0E0/SomeApp.app"))Current executable set to '/private/tmp/idb-applications/com.foo.SomeApp/SomeApp.app' (arm64).
(lldb) script lldb.target.modules[0].SetPlatformFileSpec(lldb.SBFileSpec("/private/var/containers/Bundle/Application/64B4DDB3-1049-458C-AA0B-F56AF4DCF0E0/SomeApp.app"))
True
(lldb) process connect connect://localhost:10881
(lldb) r
Process 10416 launched: '/private/tmp/idb-applications/com.foo.SomeApp/SomeApp.app/SomeApp' (arm64)
process connect 完成后,lldb 已附着到远程 debugserver,应用处于就绪但尚未启动的状态;用 lldb 的 run 命令即可启动。此后 lldb 就是一个常规调试器,可以正常设置断点、单步、查看变量等。
一个重要的使用注意点(README 明确提示):
一台已启动的 debugserver 只能同时有一个调试会话。 想要在
process connect之后开始新的调试会话,必须先用idb debugserver stop停止,再重新执行idb debugserver start。
十、小结
FBDeviceControl 把 macOS 上「访问 iOS 真机」这一被 Apple 私有框架垄断的能力,封装成了清晰的层级:
MobileDevice.framework提供底层 C 调用表(AMDefines.h),由MobileDevice/RestorableDevice两个 Swift 包装类持有;AMDevice+AMRestorableDevice通过异步通知(AMDeviceManager.swift、AMRestorableDeviceManager.swift)提供完整的设备视图,统一收敛到 Device.swift 的Device对象;AMDServiceConnection是通往各类 lockdown 服务的传输层(LockdownServiceConnection.swift),其上叠加 Plist 协议与 AFC 文件协议(FileConduit.swift);- Developer Disk Images(DeveloperDiskImage.swift、DeviceDeveloperDiskImageCommands.swift)为设备按需补充 Xcode/Instruments 等高级服务,且可直接通过
idb file --disk-images …手动管理; - 在此之上,
FBDeviceControl提供了 Instruments 客户端(InstrumentsClient.swift)、AVFoundation 视频采集(DeviceVideo.swift)与 debugserver 真机调试(DeviceDebugServerCommands.swift)等自动化能力。
理解这条链路之后,无论是直接集成框架、还是通过 idb CLI 驱动,你都能更准确地预判操作结果:哪些能力依赖 Xcode、哪些能力需要 Developer Disk Image、为什么设备发现是异步的、为什么调试前需要 --make-debuggable。这正是 FBDeviceControl 文档所勾勒的、macOS 上 iOS 真机自动化最核心的知识地图。