项目简介
命令行工具，在 Apple 芯片 Mac 上创建、修补并启动虚拟 iPhone。自动完成 IPSW 下载、DFU 恢复和自定义固件安装，支持从无补丁到完整越狱的多种变体。基于 Apple 的 Virtualization.framework 与 PCC 研究 VM 基础设施构建。
README 预览
🇰🇷한국어 | 🇯🇵日本語 | 🇨🇳中文 | 🇬🇧English\n\n# vphone-cli\n\nBoot a virtual iPhone via Apple's Virtualization.framework using PCC research VM infrastructure.\n\n\n\n## Prerequisites\n\n**Host:**\n\n- Apple Silicon\n- macOS 15+ (Sequoia)\n- Xcode + iOS SDK (cross-compiles the guest daemon)\n- [SIP/AMFI relaxation to allow private PV=3 entitlements with unsigned-binary](#sipamfi-relaxation)\n\n**Dependencies:**\n\n```bash\nbrew install python@3.13 aria2 wget gnu-tar openssl@3 ldid-procursus sshpass keystone cmake libusb ipsw zstd\n```\n\n## Install\n\n```bash\nbrew install zqxwce/tap/vphone-cli\n```\n\n## Build\n\n```bash\ngit clone --recurse-submodules https://github.com/Lakr233/vphone-cli.git\n\n./scripts/setup_tools.sh # install deps, build toolchain submodules, create the Python venv\n./scripts/build.sh # build + sign vphone-cli, bundle the .app, cross-compile vphoned\n\ncd .build/vphone-cli.app/Contents/MacOS/\nvphone-cli --help\n```\n\n## Quick Start\n\nOne command creates a VM end-to-end (download → patch → DFU restore → CFW install → first boot):\n\n```bash\nvphone-cli vm create myphone -V jb # -V / --variant\n\nvphone-cli vm launch myphone\n```\n\n## Commands\n\n`vphone-cli vm create` runs the whole pipeline; the individual steps below let you drive it manually or re-run one stage.\n\n### Manage\n\n```bash\nvphone-cli vm list # list VMs (--json for scripting)\nvphone-cli vm info myphone # show one VM\nvphone-cli vm new myphone # create an empty bundle (cpu/mem/disk options)\nvphone-cli vm config myphone --cpu 8 --memory 8192\nvphone-cli vm clone myphone myphone-2 # fast APFS clone, fresh device identity\nvphone-cli vm export myphone --out myphone.tzst # zstd fast by default (--max = xz -9); --out may be a dir (auto-names .tzst/.txz); skips restore dir + staging files\nvphone-cli vm import myphone.tzst --name restored\nvphone-cli vm rename myphone iphone16\nvphone-cli vm d
常见问题 (5)
故障排除如何修复 VPhone Clone 选项在 macOS 27 上无法正常工作的问题？
升级到 VPhone.bundle 2.9.0；修复位于提交 7d22444d 中。在 macOS 27 上，/dev 设备号可能超过 Int32.max，导致 Clone 的复制前检查在扫描已打开 /dev/null、磁盘映像、SEPStorage 或 nvram.bin 的进程时崩溃。这还会导致 vphone-cli vm clone、快照和还原功能失效。安装 2.9.0 bundle 后，请将每个现有虚拟机的 Core Bundle 设置更新为 2.9.0，然后再次使用 Clone…、快照或还原功能。
故障排除如何修复使用 apps.install 安装大型 IPA 时出现的 "IPA: archive expands beyond one GiB" 错误？
升级到包含 **icli 0.7.18 或更新版本**的构建;vphone-cli 主分支从提交 9c9446a0 起即使用该版本。在该版本中,解压上限从 **1 GiB 提高到 8 GiB**,最大条目数从 **50,000 提高到 400,000**。升级后,请重试:
vphone-launchpad-cli guest rpc <machine> apps.install '{"path":"<guest 中 .ipa 的路径>"}'此后,一个包含 96,764 个条目的 1.89 GB IPA 即可成功解压。在旧版本中,没有任何环境变量、plist 或运行时设置可以更改该限制;1 GiB 的上限是一个编译期常量。如果你仍停留在 vphone-launchpad 2.8.0/icli 0.7.17,则必须升级,或者使用更大的 kArchiveByteLimit 自行构建自定义的 icli。新的拒绝信息会包含实际大小,例如 IPA: archive expands to 8.79 GiB, over the 8 GiB limit。
故障排除如何修复 iOS 18 上 VPhone Launchpad 中的 "Set up and slim system failed" 错误 "service group(s) accounts need the trimmed service list"？
这是因为 Launchpad 2.9.5 在启用“Turn off unneeded services”（默认开启）时总是传递 --accounts-off，但精简后的服务列表仅存在于 iOS 26/27 的 vphoned 中。在 iOS < 26（例如 iOS 18.6.2）上，设置步骤会失败，重试时只会重复同样会失败的参数。解决方法：创建机器时，打开 Advanced Options → Services and Apps，将“Turn off unneeded services”关闭。这样 Launchpad 会传递 --service-profile none 而不是 --accounts-off，创建即可成功。在 iOS < 26 上这样做不会有任何损失，因为精简服务列表在这些版本中本来就不存在。正确的修复方式是让 Launchpad 仅对 trimmedServiceProfileMajors（[26, 27]）中包含的 iOS 主版本传递 --accounts-off。
故障排除为什么 Bark 在 VPhone 中显示 "Unknown Status" 且无法获取 APNs 设备令牌？
这是预期行为。VPhone 不支持获取 Apple APNs 设备令牌,也不支持接收通过 APNs 推送的远程通知,因为 APNs 注册需要 Apple 设备认证并交换私有安全令牌,而虚拟环境无法提供这些内容。目前没有修复计划。启用通知、拥有 aps-environment: production entitlement,或确认 com.apple.apsd 正在运行,都无法生成可用的令牌。作为变通方案,可以实现一个与 Bulletin Board 通信的自定义守护进程,以提供等效的通知功能。
故障排除如何修复 vphone 中 roothide bootstrap 上 SSH (OpenSSH) 无法正常工作的问题？
在带有 roothide bootstrap 的 vphone 2.1.0 中，仅通过 irisin 包管理器安装 openssh 是不够的——/private/var/containers/Bundle/Application/.jbroot-* 内仍然缺少 rootfs 符号链接。解决方法：同时从 irisin 安装 base 包。在 openssh 和 base 都安装完成后，SSH 即可正常使用，无需任何额外步骤。