我之前一直在 Mac 上用 Xcode 跑真机，插上线按一下运行，签名这块基本不用操心。今年把一个小项目挪到 Windows 上开发 iOS，用 KXBuild 配 VS Code 接着写，才发现同一套工程换个环境，问题会分三段冒出来：构建的时候先卡住，包装不进手机，装进去了点开又闪退。三段对应的原因完全不一样，混在一起查，时间很容易耗在错误的方向上。

这篇就按这三段拆开，把每段常见的几类问题、报错原文和验证命令列出来。说的都是 Windows 上开发 iOS 时会碰到的签名和真机调试，不需要开 Mac。先给一句结论： 签名问题九成出在三样东西没对齐——证书、描述文件、设备。

先确认问题卡在哪个阶段

iOS 把签名校验放在三个时间点。 KXBuild 在构建时检查证书和描述文件，报错文字和 Xcode 保持一致；安装时由手机判断这个包能不能装；启动时系统再验一次开发者模式和证书状态。看到报错先别急着改配置，先确认它出现在哪一步：构建日志里、安装返回里，还是手机弹窗里。方向和工具都不一样。

构建阶段：证书和描述文件对不上

先看构建日志开头有没有 keychain: 开头的警告。证书目录里每个 .p12 都要能读出来，password.properties 里写「文件名=密码」，少一行或者密码不对，后面很容易发展成 No signing certificate matching。

证书目录有两个位置：工程根目录的 keychain 只对当前工程生效， %USERPROFILE%\kxbuild\keychain 是所有工程共用。放错地方这一类问题，说实话我见过不止一次，感觉每换一台机器就要重踩一遍。

然后核对三件事：

• 证书类型。Debug 用 Apple Development，Release 走 App Store 或 Ad Hoc 用 Apple Distribution。只有 .cer 没有私钥，签不了。
• 团队和 Bundle ID。报错里反正会直接写出对不上的那个 Bundle ID，以它为准，不要凭印象改。
• 描述文件的能力。推送、iCloud、App Groups 在生成描述文件那一刻就固定了，后台后来新开的不会自动进去；工程里有 Widget 或通知扩展的，每个扩展的 Bundle ID 也要有各自的描述文件。

描述文件是签过名的 plist，Windows 上可以用 Git for Windows 自带的 OpenSSL 解开：

1& "C:\Program Files\Git\mingw64\bin\openssl.exe" smime -inform DER -verify -noverify -in .\keychain\MyApp_Dev.mobileprovision -out profile.plist

重点看 ProvisionedDevices、ExpirationDate、application-identifier 和证书列表。这一步看着麻烦，其实安装失败时能省很多来回（别问我怎么知道的）。

安装阶段：设备、类型和系统版本

安装失败报得最多的是 0xe8008015，提示 A valid provisioning profile for this executable was not found。它不只代表设备没注册，描述文件类型不对、过期、证书被吊销，或者包被重签过，都会报这一条。

按顺序查：

• 设备 UDID 在不在 ProvisionedDevices 里。数据线连上手机，解锁、点信任，运行 kxdevice device list，第一列就是 UDID。
• 描述文件类型对不对。App Store 类型只能走 TestFlight 或 App Store，直接装真机一定失败；给测试同事装包要用 Ad Hoc，并且把他的设备 UDID 加进去。
• 部署目标。DeviceOSVersionTooLow 说明工程的最低 iOS 版本高于手机系统，调低 IPHONEOS_DEPLOYMENT_TARGET，CocoaPods 工程还要同步改 Podfile 里的 platform。
• 旧包来源。MismatchedApplicationIdentifierEntitlement 多半是手机上原来的版本由另一个团队签名，卸载旧的再装，本地数据会丢，动手前先提醒自己一句。

只注册设备、不重新下载描述文件，问题不会自己消失。改完描述文件一定要重新构建，旧 ipa 里嵌的还是旧文件。

1kxbuild build .\MyApp.xcodeproj --install

启动阶段：开发者模式、信任和证书状态

装上了点开就退，或者弹「未受信任的开发者」，问题在启动阶段。

• iOS 16 及以上，开发证书签名的 App 要打开开发者模式：设置 → 隐私与安全性 → 开发者模式，打开后重启，重启后再确认一次。手机没和电脑配对过时这个开关不会出现，先连数据线点信任；在 Windows 上也可以用 kxdevice devmode reveal 让它显示出来。
• 「未受信任的开发者」多半出现在免费 Apple ID 签的包，或者企业 In-House 证书签的包。去设置 → 通用 → VPN 与设备管理里点信任，手机得联网啊，离线点信任会显示「尚未验证」。公司网络拦了 ppq.apple.com 也会一直验证失败，换手机热点试一次就能判断。
• 证书过期或被吊销，已经装上的开发版、Ad Hoc 版可能突然打不开；已经在 App Store 上架的版本不受发布证书过期影响。后台 Certificates 页看状态，换新证书后所有相关描述文件都要重下，再重新构建。

排查顺序

写到这儿其实就一条线：先看 keychain 警告，再核证书，再核描述文件，再核设备，收尾看手机设置。按我的经验，前三步基本就能定位，挺省事的。还拿不到具体原因时，用数据线跑一次 kxbuild build --install，或者 kxdevice install，让 iOS 把拒绝原因打出来，比在分发平台上看「无法安装」四个字有用得多。

Mac 上的 Xcode 把这套东西包在 Signing & Capabilities 面板里，自动签名确实省心，但前提是手边有一台 Mac。 KXBuild 在 Windows 上走的是同一套证书和描述文件规则，只是把文件放进 keychain 目录手动管理；生成证书这一步，除了用 OpenSSL 自己合成 p12，也可以用 Appuploader 这类工具登录开发者账号直接出证书，少折腾几步。测试人员多、设备又不固定时，Ad Hoc 收集 UDID 会很累，改用 TestFlight 更省事，它不占设备名额，也不用手动信任。

签名这件事没什么巧办法嘛，把证书、App ID、描述文件、设备四样对齐，报错自然就少了。下次再遇到装不上，先别怀疑代码，按阶段走一遍吧，多数问题十分钟内能看出方向。

更多教程可以查看官网：https://www.kxbuild.net/zh