创建你的第一台虚拟机

vphone-cli vm create 把「创建一台可启动虚拟 iPhone」的全部步骤收敛为一条命令：从下载固件到首次启动验证，端到端自动完成。本文解释每个阶段在做什么、有哪些可选变体、以及出问题去哪里看日志。

开始前

• 已完成「环境准备与安装」，尤其是 make build 与 make helper_install（CFW 阶段依赖特权 helper）。
• 宿主机不在嵌套 VM 中（嵌套环境无法 PV=3 启动，建机入口会被直接拒绝）。
• 预留足够磁盘：单台 VM 默认 64 GB 稀疏磁盘 + IPSW 缓存若干 GB；建机预检要求 VM bundle 所在卷可用空间 ≥ 25 GB，不足会在开始前直接失败（insufficientDiskSpace）。

一键建机

最简单的入口是 Make 目标（会自动构建并把全程输出写入日志目录）：

make rebuild_dev

等价的核心命令是：

.build/release/vphone-cli vm create -V dev

常用参数：

参数	作用
-V, --variant	固件变体：less / regular / dev / jb / exp
-i / -c	指定 iPhone / cloudOS IPSW 来源（缺省按固件配对表自动选择）
--cfw-only	只重装 CFW（要求 VM 已存在）
--stage-ipa <path>	附加待安装 IPA（可重复传入多个）：CFW 阶段拷进 guest，首启自动安装（less 变体不可用）
--no-keyboard	跳过键盘扩展安装（所有非 less 变体默认安装，见「变体」篇）
--no-resume	强制全量重跑（默认失败 / 中断后重跑会从断点续起，见下文「断点续跑」）
--interactive	交互模式：首启与命令注入由回车手动控制
-v / -vv / -vvv	逐级提升日志详细度

全程输出保存在 setup_logs/runs/<时间戳>/stdout.log（setup_logs/latest 软链指向最近一次）。

五个阶段详解

一条命令内部按固定顺序走完以下流程（less 跳过 CFW 阶段、jb / exp 首启后多一步 guest 内自动收尾）：

阶段 1：fw prepare —— 固件准备

下载（或从缓存取用）iPhone 与 cloudOS 两份 IPSW，解包后把 cloudOS 启动链合并进 iPhone 固件树，生成混合（hybrid）BuildManifest。产物落在 VM bundle 的 iPhone*_Restore/ 目录；IPSW 缓存在 ~/.vphone/ipsws，重复建机会自动复用。下载与缓存复用均会做 SHA-256 校验（损坏自动重新下载）；缓存目录按「最近使用」语义每 30 天自动清扫，不用手动清理。

阶段 2：fw patch —— 启动链补丁

按所选变体，对 Restore 目录中的固件组件原地打补丁：

• dfu：iBSS / iBEC
• all_flash：LLB / DeviceTree
• txm、kernelcache

安全绕过的强度随变体递增：less 最大程度保留 iOS 缓解措施（全程需 root），regular / dev / jb 逐步放开，exp 是 jb 的超集、另含反 VM 检测研究补丁。日常研究用 dev 即可。

阶段 3：DFU restore —— 刷入系统

自动把 VM 启动到 DFU 模式，抓取 SHSH blob，再把打过补丁的固件作为混合 IPSW 刷入，随后关机。刷写完成后，guest 系统持久化在 bundle 内的 Disk.img 与 SEPStorage 两个文件中。两个桥调用都带超时保护（SHSH 10 分钟、restore 45 分钟），超时自动终止子进程并失败，不会无限挂起。

阶段 4：cfw install —— CFW 安装（host-mount）

less 变体跳过此阶段。

在 VM 关机状态下，经特权 helper（com.vphone.helper）把 Disk.img 挂载到宿主机，由变体安装器写入 CFW 文件（guest 守护进程、dylib、配置等），最后离线翻转 APFS boot snapshot，使补丁后的系统可被引导，随后卸载并收尾。此阶段要求 VM 已关机，且必须提前 make helper_install。

阶段 5：First boot + Boot analysis —— 首启验证

首次正常启动 VM，自动注入初始化命令后关机（jb / exp 的越狱收尾由 guest 内 LaunchDaemon 自动完成，日志在 guest 内 /var/log/vphone_jb_setup.log）；随后再次启动并分析启动结果，判定成功或失败。成功后会把固件版本、build 与变体信息写入 VM 配置，并清理 Restore 工作树。

Standalone patch：不重跑全流程的小补丁

已建好的 VM 可以单独重打某一类补丁，无需重跑整个创建流程：

make dt_patch       # DeviceTree 补丁
make gpu_patch      # GPU bundle 补丁
make sensor_patch   # CoreMotion 传感器补丁
make sim_patch      # CoreTelephony SIM 补丁

这类操作同样要求 VM 关机。

日志在哪里

日志	位置
建机全程输出	setup_logs/runs/<时间戳>/stdout.log
启动日志	setup_logs/boot.log（普通启动）、setup_logs/boot_dfu.log（DFU 启动）
JB 收尾日志	guest 内 /var/log/vphone_jb_setup.log

启动类问题先看 boot.log 是否出现 panic；建机流程失败则回看对应阶段标记（=== 阶段名 ===）之后的输出。

断点续跑（Checkpoint）

vm create 把各阶段完成进度持久化为断点 ledger（bundle 内 .vphone-create-state.json）。失败、取消甚至断电之后，直接重跑同一条命令即可：已成功阶段（指纹匹配 + 产物校验通过）自动跳过，从第一个未完成阶段续起——动辄 5–30 分钟的 DFU restore 不会白白重做。

• 跳过的阶段照样会发出对应的进度事件，Manager 创建向导无需任何改动。
• 成功交付后断点状态自动删除，维持「全量重跑」语义。
• --no-resume 强制从头全量重跑；--cfw-only 不读取也不写断点。

建完之后

vphone-cli vm list                # 查看库内 VM
vphone-cli vm launch <name>       # 启动某台 VM
vphone-cli vm clone <name> <new>  # 复制一台（APFS 快速克隆，同设备身份）
vphone-cli vm snapshot save <name> --as <快照名>   # 保存整盘快照

更多命令见「CLI 命令参考」；图形化管理见「vphone-manager 多 VM 管理 GUI」。