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.gitcd 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://<vm-ip>: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 科技，转载请注明出处】
