项目概述

vphone-cli 是一款基于 Apple Virtualization.framework 开发的命令行工具，旨在利用 PCC 研究的虚拟机基础设施，在 macOS 上启动虚拟 iPhone。该工具支持从下载固件、修补引导链到安装自定义固件（CFW）的全流程自动化，并为开发者提供了多种安全绕过分级的变体选项。

系统要求与依赖

主机环境：

• 硬件：Apple Silicon（苹果自研芯片）Mac
• 系统：macOS 15 (Sequoia) 或更高版本
• 开发工具：Xcode 及 iOS SDK（用于交叉编译客户机守护进程）
• 权限配置：需放宽 SIP（系统完整性保护）或 AMFI（Apple 移动文件完整性）限制，以允许未签名二进制文件使用私有 PV=3 权限

软件依赖：

用户可通过 Homebrew 安装必要组件，包括 python@3.13、aria2、wget、gnu-tar、openssl@3、ldid-procursus、sshpass、keystone、cmake、libusb、ipsw 及 zstd。

安装与构建

快速安装：

brew install zqxwce/tap/vphone-cli

源码构建：

克隆仓库并初始化子模块后，运行设置脚本以安装依赖、构建工具链及创建 Python 虚拟环境，随后执行构建脚本生成 .app 包并交叉编译 vphoned。

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

cd vphone-cli

./scripts/setup_tools.sh

./scripts/build.sh

核心功能与使用

一键部署

vphone-cli 支持端到端自动化流程，单条命令即可完成虚拟机创建、固件下载、修补、DFU 恢复、CFW 安装及首次启动。

# 创建名为 myphone 的越狱版虚拟机

vphone-cli vm create myphone -V jb

# 启动虚拟机

vphone-cli vm launch myphone

虚拟机管理

工具提供完整的生命周期管理命令，包括列出、查看信息、新建、配置资源（CPU/内存）、克隆（APFS 快速克隆）、导出/导入（支持 zstd/xz 压缩）、重命名及删除虚拟机。

固件变体选择

通过 --variant 参数，用户可选择五种不同安全绕过程度的变体：

• less：最小化修补，保留 iOS 缓解措施
• regular：绕过 AMFI/SSV/Img4/TXM
• dev：增加 TXM 权限及调试绕过
• jb：完整越狱，自动安装 Sileo 和 TrollStore
• exp：实验性超集，包含反虚拟机检测研究补丁

连接与交互

• SSH 访问：越狱版默认用户为 mobile（密码 alpine），常规/开发版为 root，端口均为 22222。
• VNC 访问：通过 vnc://:5901 连接图形界面。

数据存储结构

所有虚拟机数据默认存储于 ~/.vphone/ 目录下，确保应用包的可移植性。用户可通过环境变量 $VPHONE_ROOT 重定向根目录，或使用 $VPHONE_LIBRARY_ROOT 单独指定虚拟机库位置。目录结构包括 VMs（虚拟机包）、ipsws（固件缓存）、tools（APFS 工件）、debs（越狱包缓存）及 venv（Python 环境）。

常见问题与排查

• 进程被杀（Killed）：通常因 AMFI/调试限制未绕过导致，需检查启动参数 amfi_get_out_of_my_way=1 或使用 amfidont 白名单。
• 虚拟化不可用：宿主 Mac 不能是虚拟机，PV=3 不支持嵌套虚拟化。
• 卡在“按 Home 键”：通过 VNC 连接后，右键（或双指点击）模拟 Home 键操作。
• 地区限制：初始化时避免选择日本或欧盟地区，以防监管检查失败，建议选择美国。
• EXC_GUARD 崩溃：iOS 18 基础版本启用此保护，需使用 --force-exc-guard 重新修补固件。
• ldid 内存泄漏：旧版 ldid-procursus 存在已知 Bug，建议从源码重建最新版本（brew install --HEAD ldid-procursus）。

自动化支持

vphone-cli 暴露主机控制套接字（vphone.sock），支持程序化控制截图、触摸、滑动、硬件按键及剪贴板操作，每个操作均返回内联截图，适用于 AI 驱动的端到端自动化测试场景。

【星途科讯 图文丨略略 首发于ZAKER科技，转载请注明出处】