vphone-cli：用 Apple 的 Virtualization…

一、在一台 Mac 上启动一台虚拟 iPhone

README 的标题下面只有一行说明，也是整个项目的定义：Boot a virtual iPhone via Apple’s Virtualization.framework using PCC research VM infrastructure.

这句话里有两个限定值得留意。第一，它用的是 Apple 官方的 Virtualization.framework，不是第三方模拟器内核——这意味着性能与兼容性直接受益于系统框架，代价是平台被锁死。第二，PCC research VM 基础设施指的是 Apple 为「研究用虚拟机」开放的那一套能力，它需要主机做相应的授权放宽才能运行私有 PV=3 entitlement 的未签名二进制。

从仓库元数据看，这是一个 2026 年 2 月 26 日创建、主语言 Swift、MIT 许可的项目，当前 11,285 Stars、1,433 Forks，而开放 Issue 只有 23 个。Stars 与 Issue 的比例低得异常，一种合理的解释是：它的用户群体高度同质（都是 Apple Silicon + macOS 15+ 的研究者），踩坑点集中在 README 已经写明的那几处。

二、前置条件：四件套

README 把 Prerequisites 分成 Host 与 Dependencies 两块。Host 侧四条，一条都不能少：

• Apple Silicon——Intel Mac 直接出局
• macOS 15+（Sequoia）
• Xcode + iOS SDK——用途是交叉编译 guest 端的守护进程（vphoned）
• SIP/AMFI 放宽——为了允许私有 PV=3 entitlements 与未签名二进制

第三条解释了为什么这不是一个「下载即用」的工具：仓库里有一个跑在虚拟机内部的守护进程需要在主机上交叉编译，所以 Xcode 和 iOS SDK 是硬性依赖。第四条我在第七节单独展开。

Dependencies 是一条 brew 命令，十一个包，每个都有明确分工：

brew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd

aria2 与 wget 负责拉固件，ipsw 处理 Apple 固件格式，ldid-procursus 做签名，zstd 是后面导出 VM 的默认压缩，libusb 与 sshpass 分别对应 DFU 与登录，keystone 是反汇编引擎，python@3.13 则用于自动创建的虚拟环境。

三、brew 一行装，或自己从源码编

装预编译版本只要一行，走的是第三方 tap：

brew install zqxwce/tap/vphone-cli

想自己编译，README 给的三步里第一步就带 –recurse-submodules——工具链是以子模块形式挂进来的：

git clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git

./scripts/setup_tools.sh      # install deps, build toolchain submodules, create the Python venv
./scripts/build.sh            # build + sign vphone-cli, bundle the .app, cross-compile vphoned

cd .build/vphone-cli.app/Contents/MacOS/
vphone-cli --help

注意产物是 .app 包而不是裸可执行文件——因为要签名、要带 Resource（后面会提到的 vphone-amfidont），命令行入口藏在 Contents/MacOS/ 里。

四、vm create 背后跑了六步

Quick Start 只有两行，但 README 明确说 vphone-cli vm create 端到端跑完了整条流水线：download → patch → DFU restore → CFW install → first boot。

vphone-cli vm create myphone -V jb        # -V / --variant

vphone-cli vm launch myphone

想手动驱动或重跑某一个阶段，README 把六步拆开列了出来：

vphone-cli vm new myphone                              # 1. empty bundle
vphone-cli fw prepare myphone --iphone-version 26.1     # 2. download + merge IPSWs
vphone-cli fw patch myphone --variant jb                # 3. patch the boot chain

vphone-cli vm launch myphone --dfu &                    # 4. boot into DFU (background)
vphone-cli restore myphone --get-shsh                   #    fetch SHSH
vphone-cli restore myphone                              #    DFU restore
vphone-cli vm stop myphone                              #    stop the DFU boot

vphone-cli cfw install myphone --variant jb             # 5. install CFW (host-mount; asks for sudo)
vphone-cli vm launch myphone                            # 6. first boot

想升级到更新的 iOS，把 fw prepare 指向本地 IPSW 即可：–iphone-source /path/to.ipsw –cloudos-source /path/to.ipsw。注意这里要同时给 iPhone 固件与 cloudOS 固件两个路径——虚拟 iPhone 其实是两份固件的组合，这一点在后面的环境表里也能印证。

日常管理是另一组命令，几个细节很实用：vm list 支持 –json 便于脚本化；vm clone 走的是快速 APFS 克隆并生成全新设备标识；vm export 默认用 zstd 快速压缩，–max 则切到 xz -9，–out 可以直接给目录（自动命名 <vm>.tzst / .txz），并且会跳过 restore 目录与暂存文件。

vphone-cli vm config myphone --cpu 8 --memory 8192
vphone-cli vm clone myphone myphone-2       # fast APFS clone, fresh device identity
vphone-cli vm export myphone --out myphone.tzst
vphone-cli vm import myphone.tzst --name restored
vphone-cli vm rename myphone iphone16
vphone-cli vm delete iphone16

五、五种固件变体：从 4 个补丁到 141 个

Firmware Variants 一张五行表，是整份 README 里信息密度最高的地方。五种变体呈严格的安全绕过递增关系，通过 –variant 传入：

• less——启动链 4 个补丁，CFW 2 个阶段。Patchless，保留 iOS 各项缓解机制。
• regular——42 个补丁，10 个阶段。绕过 AMFI / SSV / Img4 / TXM。
• dev——53 个补丁，12 个阶段。在 regular 之上加 TXM entitlement / debug 绕过。
• jb——113 个补丁，14 个阶段。在 dev 之上加完整越狱，首次开机自动装 Sileo 与 TrollStore。
• exp——141 个补丁，18 个阶段。jb 的超集，再加反虚拟机检测的研究用补丁。

数字本身的梯度很说明问题：从 less 的 4 个到 regular 的 42 个，是一个数量级的跨越——也就是说「保留缓解机制」与「绕过 AMFI/SSV/Img4/TXM」之间不存在中间态。而 jb 相对 dev 又从 53 跳到 113，多出来的 60 个补丁几乎全花在越狱环境本身上。逐组件的拆分明细在仓库的 research/0_binary_patch_comparison.md 里。

从合规角度看，这张表的存在本身就是一种信息透明：每个变体绕过什么、补丁多少，都写在明面上，使用者需要自己判断所处司法辖区与研究授权允许的边界。

六、连进去，以及东西放在哪

连进虚拟机只有两种方式，README 一句话交代完：

• SSH（jailbreak 变体）：ssh -p 22222 mobile@<vm-ip>，密码 alpine
• SSH（regular / dev 变体）：ssh -p 22222 root@<vm-ip>
• VNC：vnc://<vm-ip>:5901

端口固定为 22222 与 5901，用户名随变体变化——jailbreak 变体给的是 mobile 用户，非 jailbreak 变体直接给 root。

Locations 一节交代了目录树，并说明了设计理由：所有 vphone-cli 创建的东西都在 ~/.vphone/ 下，刻意放在仓库与 .app 之外，这样签名过的 bundle 才能保持可移植。

• ~/.vphone/VMs/——VM bundle 库，每个 VM 一个目录，可用 $VPHONE_LIBRARY_ROOT 覆盖
• ~/.vphone/ipsws/——下载的 iPhone + cloudOS IPSW 缓存，跨 VM 复用
• ~/.vphone/tools/——fw prepare 期间拉取的 APFS seal-volume 产物（apfs_sealvolume_<version>）
• ~/.vphone/debs/——jb / exp 的 CFW 安装会往 guest 里放的 .deb 包缓存（Sileo、apt 等）
• ~/.vphone/venv/——自动创建的 Python 环境，可用 $VPHONE_VENV_DIR 覆盖

覆盖优先级 README 也写死了：单项覆盖（$VPHONE_LIBRARY_ROOT、$VPHONE_VENV_DIR）胜过 $VPHONE_ROOT，后者又胜过默认的 ~/.vphone；而 ipsws/、tools/、debs/ 三个缓存永远直接挂在生效的那个 root 之下。

七、SIP 与 AMFI：两条路

这是上手过程中最容易卡住的一步。README 给了 Option A 与 Option B，区别是放宽到什么程度。

Option A（最宽松）——先完全关闭 SIP，再用 boot-arg 关掉 AMFI。在恢复模式（长按电源键 → Terminal）里执行：

csrutil disable
csrutil allow-research-guests enable

然后重启回 macOS，设置 boot-arg（必须 SIP 完全关闭才生效）：

sudo nvram boot-args="amfi_get_out_of_my_way=1 -v"   # reboot after

Option B（只放宽调试）——保留 SIP 开启（仅去掉 debug 项），系统级 AMFI 仍然生效，改为把单个二进制加入白名单：

csrutil enable --without debug
csrutil allow-research-guests enable

然后重启回 macOS 执行：

vphone-amfidont         # .build/vphone-cli.app/Contents/Resources/vphone-amfidont for local builds

两条路都要执行 csrutil allow-research-guests enable——这正是 Apple 为研究用虚拟机留的那道官方开关。选 A 还是 B，本质上是「整机安全性」与「白名单粒度」之间的取舍。

八、18 组已验证环境

Tested Environments 是一张三列表格，列了 18 行实测组合：Host / iPhone / CloudOS。读这张表能看出不少东西。

主机侧出现的型号有 Mac16,11、Mac16,8、Mac16,12、Mac16,6 四种，系统版本从 26.2、26.3、26.4.1、26.5.1、26.6.1 一直到 27.0b2（测试版）——覆盖面相当激进。iPhone 固件一律是 17,3 这个机型标识，iOS 版本从 18.6.2（22G100）一路铺到 27.0（24A5430a），中间还有 26.0、26.0.1、26.1、26.3、26.3.1、26.4、26.5、26.5.2、26.6、26.6.1 等众多小版本。CloudOS 一侧则相对稳定，只有 26.1-23B85、26.3-23D128、26.4-23E5207q 三个版本，多数行复用同一个 cloudOS。

这个矩阵传达的信息很实在：iPhone 固件版本是主要变量，cloudOS 是慢变量。升级 iOS 时你真正要试的是 iPhone IPSW，而不是整套环境。

九、FAQ 里的七个坑

README 的 FAQ 是七条，每条都是一个具体的故障现象加解法，信息量远超一般的「常见问题」。

zsh: killed ./vphone-cli——AMFI / debug 限制没绕过，回到前置条件，用 amfi_get_out_of_my_way=1 或 amfidont。

Virtualization is not available on this hardware——你的 Mac 本身就是一台虚拟机，PV=3 guest 无法嵌套启动，需要一台非嵌套的 macOS 15+ 主机。

卡在 Press home to continue——用 VNC 连进去，右键（双指点按）模拟 Home 键。

系统应用装不上——iOS 初始化时不要把地区选成日本或欧盟（额外的合规检查虚拟机无法满足），选美国之类即可。

应用启动崩溃，报 EXC_GUARD / GUARD_TYPE_MACH_PORT——用 vphone-cli fw patch <name> –variant <v> –force-exc-guard 重新打补丁再刷机；以 iOS 18 为基版时这个选项是默认开启的。

安装 .ipa / .tipa——用运行中虚拟机的 Install 菜单，拖拽或文件选择都行。

cfw install 卡在给系统二进制重签名、内存无限上涨——这是 ldid-procursus 从当前 Homebrew stable 到 2.1.5-procursus7 的已知 bug：bytes(uint64_t) 调用 __builtin_clzll(0) 时没有零值保护，属于未定义行为，在这个构建上解析成长度 0，导致无符号循环计数器下溢——ldid 于是一次写一个字节到不断增长的缓冲区而不终止。触发条件是任何包含整数值恰好为 0 的 entitlements plist（部分真实的 Apple 系统二进制确实有）。上游已修复但尚未发 tagged release，解决办法是从源码重装：brew install –HEAD ldid-procursus && brew link –overwrite ldid-procursus；已经卡住的先 sudo kill -9 <pid> 杀掉挂起的 ldid 进程。

最后这条 FAQ 的细节深度，基本就是这个项目工程气质的缩影：不只告诉你怎么绕，还把未定义行为、循环下溢和触发条件讲清楚。

十、自动化：vphone.sock 与 vphone-mcp

README 的 Automation 一节只有一段，但指向了一个很实际的方向：vphone-cli 对外暴露一个宿主控制套接字 <bundle>/vphone.sock，可编程控制截图、触摸、滑动、硬件按键与剪贴板，每个动作都会内联返回一张截图——这个设计明显是为 AI 驱动的端到端测试准备的：模型发一个动作，立刻拿到视觉反馈，再决定下一步。

社区已经有一层封装：vphone-mcp，一个把控制套接字包成 MCP server 的项目。致谢部分则指向 wh1te4ever/super-tart-vphone-writeup——这份 writeup 是整件事的技术源头。

十一、写在最后

vphone-cli 的价值在于把一个原本散落在多篇 writeup、多个脚本里的流程，收敛成了一组语义清晰的命令：vm new、fw prepare、fw patch、restore、cfw install、vm launch。每一步都能单独重跑，状态全部落在 ~/.vphone/ 一个可迁移的目录树里，VM 还能用 APFS 快速克隆与 zstd 导出。这套工程化，是它能在半年多时间里攒下 11,285 Stars 的主要原因。

它同时也很诚实：主机要求、SIP/AMFI 的两条放宽路径、18 组实测环境、七个已知坑连同上游 ldid 的未定义行为分析，全都写在 README 里。对想做 iOS 底层研究的人来说，光是这份文档本身就值得一读。

在撰写本文的过程中，我主要参考了以下来源：GitHub 仓库 Lakr233/vphone-cli 的 README（Prerequisites / Install / Build / Quick Start / Commands / Firmware Variants / Running & Connecting / Locations / SIP-AMFI Relaxation / Tested Environments / FAQ / Automation 各节），以及仓库 meta 数据。文中数值以官方公开信息为准，可能随版本更新而变化。