iPhone 真机调试失败排查，签名、描述文件、开发者模式等问题

上周帮同事救火一个真机运行失败：Xcode 里点运行，弹「Unable to install App」，archive 能出包、模拟器跑得好好的，一接手机就装不上。他前一天还能跑，中间只换了台测试机。这类问题我在不同团队见过不少，报错文案五花八门，但真机安装要过的校验就那几关——签名、描述文件、设备信任、开发者模式，逐关过一遍基本都能定位。

先把「为什么装不上」拆开看。一台 iPhone 装 App 前会依次核对几件事：包得用有效的开发者证书签过名；签名要和一份描述文件匹配，描述文件上写着允许装哪些设备（UDID 列表）、配合哪种证书；设备第一次装开发包，还要被用户在「VPN 与设备管理」里信任一次；iOS 16 之后多了一道手续，开发者模式要手动打开。这几关层层递进，哪一关不过，表现在外都是装不上或者装了打不开，而报错未必说清卡在哪一关。所以排查的思路不是盯着报错文案发愁，是拿着几关当清单逐个过。

签名和证书：第一关

关键词：does not have a valid signature、code signature invalid。

排查点有几个：打包用的证书有没有过期——开发证书有效期一年，到期忘了续，前一天好好的包第二天就装不上；证书和描述文件是不是一对，中途重建过描述文件、换了签名证书，旧包就配不上了；证书类型有没有用对，拿发布证书去签调试包也会装不上。

有个高频坑值得单独说：免费 Apple ID 签的包有效期只有 7 天。个人练手、临时演示用免费账号没问题，但「昨天还好的，今天突然装不上」这种情况，先把 7 天有效期排第一个。

用免费账号做演示或者给客户看包之前，记得到期当天重新签一次——这个坑踩过一次就忘不了。

描述文件与设备名单：第二关

关键词：No profiles for xxx were found、device is not registered。

开发类和 Ad Hoc 类描述文件里，都写着一份允许安装的设备名单。换一台测试机、来了新同事的手机、名单动过但没重新生成描述文件，装的时候就被拦在门口。付费开发者账号的 Ad Hoc 名额是每年 100 台，满了要先清理旧的；描述文件本身也有一年有效期。

顺序上还有个细节：设备名单变了，光换描述文件不够，要用新描述文件重新打包签名，只替换文件不重签，校验照样不过。

设备信任与开发者模式：第三关

关键词：Untrusted Developer，或者 App 装上了、图标灰着点不开。

第一次往设备上装开发包，需要去「设置 → 通用 → VPN 与设备管理」里信任对应的开发者证书；iOS 16 之后还多一步，去「设置 → 隐私与安全性 → 开发者模式」把它打开并重启手机。这两个开关换新机、恢复出厂、重置设置之后都要重来一遍，老开发偶尔也会在这栽一次。

系统与连接类：另一类问题

还有一类装不上和签名无关，现象是设备列表里压根看不到手机，或者传到一半断掉。常见的：手机系统版本比开发工具支持的还新（工具版本落后于 iOS 版本，提示「不支持此设备」时多半要升级工具让它认识新系统）；数据线只供电不传数据，换根线就好；第一次连电脑没点「信任此电脑」；无线调试和电脑不在同一网络。这类问题先解决连接，再回去看签名那几关。

每关的排查工具：Xcode 的日志

写 Xcode 的话，「Window → Devices and Simulators」是排查真机问题的第一现场：设备连没连上、描述文件什么时候过期、安装失败的具体日志，都能在这里看。报错文案对不上号时，把它翻出来比猜快得多。

不想跟这套配置打交道，有没有省事的路线

上面几关是 iOS 真机调试的固有流程，Xcode 只是把它完整暴露给你。另一条路是把这套流程收进一体化工具：用 KXApp 这类 IDE，连接 iPhone 后一键构建并安装到真机，不用导出 IPA、不用在签名面板里来回配，改完代码快速同步到手机看效果。它主打的是零门槛上手——新建项目、写代码、连真机运行走同一套流程，对刚学 iOS、或者只想快速验证界面的场景，比每次把证书、描述文件捋一遍省事。当然 iOS 的校验本身还在，只是不用你手动伺候。

路线怎么挑看场景：个人学习、偶尔验证界面，免费账号加常规工具就够；要推送、TestFlight、上架，付费开发者账号跑不掉；团队里设备多、描述文件维护频繁，把证书和描述文件交给统一的管理工具处理更稳；只想快速跑界面看效果，KXApp 这类免 Xcode 的一键真机运行能省掉大段流程。几条路线不冲突，按手头的事挑就行。

几个常被问到的点

• 报错只说「Unable to install」没提原因，先查哪关？ 先看设备和信任这关（开发者模式、VPN 与设备管理），再回头查签名和描述文件——这三种占了大头。
• 没买开发者账号能真机调试吗？ 能。免费 Apple ID 可以签，限制是 7 天有效期、设备数量少、推送等能力不可用，到期重新签一次即可。
• 描述文件没过期、证书也有效，怎么还是装不上？ 查两者是不是同一对：Bundle ID 对不对得上、描述文件里有没有这台设备；还不行就删掉手机上旧的 App、重启设备再装一次，缓存问题这么处理基本就通了。
• 模拟器好好的，真机才出问题，是代码问题吗？ 多数不是。模拟器不校验签名设备那几关，真机才校验——所以先排查配置，再怀疑代码。

真机测试运行的时候失败看着吓人，其实拆开就是几关校验：签名有效、描述文件对得上、设备在名单里、该信任的信任、开发者模式开着。报错文案对着上面逐关过，多数问题十分钟内能定位；把这几关理顺了，真机调试也就正常了