环境准备与安装

第一次运行 vphone 前的完整准备流程：系统要求、工具链安装、构建签名与特权 helper 安装。

vphone 基于 Apple 的 Virtualization.framework，在 macOS 上启动以 PCC（Private Cloud Compute）research VM 形态运行的虚拟 iPhone，供安全研究使用。本文带你完成从零到第一次启动的全部准备工作。

系统要求

项目	要求
操作系统	macOS 15（Sequoia）或更高版本
硬件	Apple Silicon Mac（虚拟 iPhone 为 arm64 guest，仅支持 arm64 宿主）
安全策略	SIP / AMFI 已放宽（否则带私有 entitlements 的二进制无法运行）
运行环境	不能在嵌套虚拟机内运行（宿主必须直接使用 Hypervisor）
预装工具	Xcode 命令行工具、Homebrew、Go ≥ 1.25

启动 PV=3 cloudOS 虚拟化依赖 Apple 私有 entitlement，因此整个项目要求宿主机放宽 SIP/AMFI。这也是它定位为「研究机专用」工具、不适合普通生产环境的原因。

git clone <仓库地址> vphone-cli
cd vphone-cli
make setup_tools

make setup_tools 会安装所需的 brew 包、构建 trustcache / insert_dylib 等辅助工具，并创建项目 Python 虚拟环境 .venv（内含刷机桥依赖的 pymobiledevice3）。前置条件是已预装 Go ≥ 1.25。

source .venv/bin/activate

项目约定所有 Python 依赖只装进这个 venv，请勿在系统全局安装。

make build

产物为 .build/release/vphone-cli（release 构建 + adhoc 签名 + 注入私有 entitlements），同时会构建网络 sidecar。

⚠️ 不要单独执行 swift build。 裸 swift build 产出的二进制没有签名、缺少 PV=3 所需的私有 entitlements，启动 VM 时会在运行时直接失败。所有日常构建都必须走 make build。

常用构建相关 target：

命令	作用
`make build`	构建并签名 `vphone-cli` 与网络 sidecar（日常开发用这个）
`make help`	列出全部可用 target 与说明
`make test`	运行 Swift 单元测试
`make clean`	清理构建产物

make helper_install

这会安装 com.vphone.helper 特权助手（安装步骤需要 sudo 授权）。后续的 cfw install（向关机状态的 VM 磁盘写入 CFW 文件）与 vm create（端到端建机）都依赖它完成挂载等 root 操作。跳过此步会在建机进行到 CFW 阶段时报错。

make boot        # 以 GUI 窗口方式启动虚拟 iPhone
make boot_dfu    # 以 DFU 模式启动（用于固件刷写）

make boot 会自动完成 bundle 打包与 guest 守护进程（vphoned）的编译推送，然后弹出虚拟 iPhone 窗口。

make test                            # 运行单元测试
.build/release/vphone-cli preflight  # 宿主可启动性诊断

preflight 会检查嵌套 VM、SIP/AMFI 状态、签名有效性等，失败项会附带修复指引；加 --assert-bootable 可在不可启动时以非零退出码结束，适合脚本化检查。