参考

常见问题

Q: 需要越狱吗？

不需要。只要 iPhone 打开开发者模式，再装一个签名过的 XCTest runner；iphone-use setup 会用你自己的 Xcode 开发团队构建、签名并安装它。

Q: 没有手机能试吗？

可以，目前是预览：iphone-use simulator start "iPhone 16 Pro" 会为 iOS 模拟器构建并启动 runner 和守护进程，需要 Xcode，不需要手机、Apple ID 和签名。模拟器没有相机、App Store 应用、真实推送和 Face ID，需要这些的任务只能在真机上做。

Q: 怎么卸载？

先运行 ~/.iphone-use/uninstall.sh --dry-run 看会删掉什么，去掉 --dry-run 就真的卸载。

Q: 装好之后我自己还能用手机吗？

能。同时按住两个音量键可以结束 iOS 的 UI 自动化；也可以运行 iphone-use pause（之后用 iphone-use resume 恢复），或在网页上点「交还」按钮，在你交回之前 agent 的输入都会被拒绝。没有 agent 活动也没人观看时，守护进程 5 分钟后也会自己释放手机。

安装前后最常被问到的问题，简短作答。更详细的说明见安装、它怎么工作和完整指南。

安装

需要越狱吗？

不需要。只要 iPhone 打开开发者模式，再装一个签名过的 XCTest runner；iphone-use setup 会用你自己的 Xcode 开发团队构建、签名并安装它。

能用 Windows 或 Linux 托管手机吗？

不能。手机由运行 iphone-use 守护进程的 Mac 托管。其他电脑（包括 Windows 和 Linux）可以访问这台 Mac 提供的网页和接口，但它们本身不是设备宿主。

支持哪些 Mac、iPhone 和 iOS 版本？

Mac 需要 macOS 15 以上和完整的 Xcode.app（只装命令行工具不够）；iPhone 需要 iOS 15 以上并打开开发者模式。免费 Apple ID（个人团队）可以给 runner 签名，但描述文件需要定期续签；用 App Store Connect API 密钥签名则不需要 Xcode 账号。

iOS 15 和 16 不用升级，但走单独的旧版路径，需要付费开发者账号的 App Store Connect API 密钥。iOS 14 及更早版本不支持。

没有手机能试吗？

可以，目前是预览：iphone-use simulator start "iPhone 16 Pro" 会为 iOS 模拟器构建并启动 runner 和守护进程，需要 Xcode，不需要手机、Apple ID 和签名。模拟器没有相机、App Store 应用、真实推送和 Face ID，需要这些的任务只能在真机上做。

能走 Wi-Fi 吗？

能。第一次用数据线配好，之后守护进程通过 CoreDevice 的加密 Wi-Fi 隧道连手机；插着线时仍优先走 USB。按维护者的实测，走隧道一次点击约 330–380 毫秒，USB 约 280 毫秒。iOS 15/16 的手机改走局域网中继，请求有签名但不加密。如果手机的 iOS 拒绝通过 Wi-Fi 启动 runner，每次 runner 需要重启时都得重新插线。

怎么卸载？

先运行 ~/.iphone-use/uninstall.sh --dry-run 看会删掉什么，去掉 --dry-run 就真的卸载。

使用手机

会动我 Mac 的光标或抢焦点吗？

不会。不管是 agent 还是你在浏览器里操作手机，它都不碰 Mac 的屏幕、光标和窗口焦点。

能操作已经登录的 App 吗？

能。它操作的就是手机上现有的 App，沿用其中的登录状态。遇到登录、锁屏密码、Face ID，agent 会停下来请你在手机上完成，绝不向你要密码或验证码。

禁止截屏的 App 怎么办？

银行、支付类 App 会把截屏涂黑。这时截图返回的是屏幕元素的线框图，agent 按元素而不是像素来操作。能读到什么取决于 App 暴露了哪些元素，不保证每个页面都可读。

装好之后我自己还能用手机吗？

能。同时按住两个音量键可以结束 iOS 的 UI 自动化；也可以运行 iphone-use pause（之后用 iphone-use resume 恢复），或在网页上点「交还」按钮，在你交回之前 agent 的输入都会被拒绝。没有 agent 活动也没人观看时，守护进程 5 分钟后也会自己释放手机。

为什么手机会要我输锁屏密码？

每次启动 runner，手机都可能要求输入锁屏密码来开启 UI 自动化，而锁屏密码没法替你输入。所以守护进程会释放空闲的手机，而不是全天反复重启 runner；对设了锁屏密码的手机，已经在运行的 runner 则会保留，不再释放。

能同时操作两台手机吗？

能。给第二台手机装一个命名实例（./install.sh --instance lab --udid <UDID>）。每台手机有独立的守护进程、runner、令牌和端口，MCP 调用可以用 instance 参数选择。

iOS App 在 App Store 上吗？

不在。iphone-use setup-app 用你自己的签名团队构建并安装到手机上。付费开发者团队得到完整版，还能不经 Mac 控制它所在的手机（iOS 17.4 及以上）；免费 Apple ID 得到远程控制版，用来操作由 Mac 提供服务的手机。

项目

还用 WebDriverAgent 或 iPhone 镜像吗？

不用了。自研 XCTest runner 从 v0.14.0 起取代了 WebDriverAgent，接口仍与它兼容；iPhone 镜像后端在 v0.9 就已移除。

用什么许可证？是开源的吗？

PolyForm Shield 1.0.0。这是源码可见许可，不是 OSI 认可的开源许可：允许符合条款的非竞争用途、修改和分发，禁止用它提供竞争产品或服务，包括免费竞品。以前按 MIT 发布的版本仍保留原有授权。详见 LICENSING.md。

会上报遥测吗？

不会。守护进程里有匿名使用计数的代码，但发行版不带项目令牌，所以什么也不发。即使设了令牌，IPHONE_USE_TELEMETRY=0 或 DO_NOT_TRACK=1 也能彻底关掉。详见隐私与安全。

在哪里报 bug？

在 GitHub issues。某个 flow 的问题请报到 flow 源；你同意后，agent 也可以用 phone_flow_report 替你提交。