最怕的不是证书过期这件事本身而是你在打包上传的深夜里突然撞见一行红字然后才想起来哦那张Distribution证书好像早就到期了。我接手过的好几个项目都经历过这个场面包括大版本上线前夜临时发现发不了包也包括客户那边急着要测试包时重新配签名。这篇文章我就把处理iOS生产证书过期的完整思路和操作摊开讲从备份到吊销到重新生成证书、更新描述文件再到Xcode里的重新签名和后续的隐患排查一次说清楚。适合所有负责iOS打包、上架、维护分发流程的开发者或团队维护者尤其是刚接手项目、对证书链还不太熟的CocoaPods熟练工、CI/CD脚本配置人——别问问就是我都当过。1. 证书过期的现场长什么样1.1 你在哪个环节突然卡住生产证书过期最容易暴露的时间点有三个Archive完成后上传App Store Connect弹出一句类似iTunes Store operation failed的提示然后就没有然后了。Xcode报签错比如No signing certificate iOS Distribution found或者更气人的Provisioning profile doesnt include signing certificate。CI/CD脚本里调用xcodebuild或altool时明明昨天还好的流水线今天换了个洞传不上去。这三种现场我都见过而且有一个共同特点报错信息里不会直接写证书过期四个字。Xcode给你的第一层提示往往是很宽泛的Signing错误你得自己去打开开发者后台才会发现哦那张证书旁边有个逾期红字。1.2 先把生产证书这个叫法对齐在iOS生态里生产证书一般指Distribution Certificate也就是分发证书。但很多团队把它和另外几张东西混在一起导致排查方向跑偏。它们不是一回事证书/凭据作用范围过期带来的直观后果Apple Distribution分发证书上传App Store的包签名、Ad Hoc分发无法重新打包上传已上架App不受影响Development开发证书调试安装到设备真机调试建不起来APNs推送证书 / Auth Key远程推送服务端认证推送发不出去App内其他证书Pass、VoIP等各自专项对应业务失效所以你在处理生产证书过期时要确认自己操作的是后台里Certificates, Identifiers Profiles下面那张Apple Distribution旧版后台叫iOS Distribution。至于推送证书那是另一件事后面我会专门拿出来说因为它混进来太常见了。1.3 过期的真实杀伤力比你想象中小先说个定心丸App Store里已经上线的App不会因为你的Distribution证书过期而闪退也不需要用户重新下载更新。系统在安装时已经验证过签名发行包签名的有效性看的是签名那一刻的证书状态而不是你此刻设备上是否可以再次验证。这一点和马上完蛋的直觉相反我当年第一次处理时也以为是天塌了结果用户侧毫无感知。真正瘫痪的是新的构建动作你不能用这张过期证书去签任何新包你签出来的App Store构建上传不上去Ad Hoc测试包没法再生成如果团队里有人的本地Keychain只存了旧证书他的打包也会一起卡住所以结论是证书过期不是灾难它只是拦截了你下一步的发布动作。2. 动手前先把私钥和旧证书抢救出来2.1 私钥比那串证书名值钱得多很多人犯过的错误直接去后台把过期证书Revoke然后让Xcode自动签名结果发现新证书装不回来——因为没有私钥或者私钥不在当前这台电脑上。记住一个概念证书文件.cer只是公钥加上一堆身份信息真正用来签名的是你Keychain里的私钥。私钥和证书是配对关系只有它们同时存在才会形成一个可签名的身份。这就好比证书是门禁卡私钥是门禁卡里内置的芯片两者缺一个你都进不了门。所以更新证书前第一件事不是吊销而是看当前这台Mac的Keychain里旧证书下面有没有展开一个私钥。具体操作打开钥匙串访问Keychain Access在左侧选择登录和我的证书搜索Distribution点击证书前的三角形看下面是不是有一把钥匙图标如果有恭喜你拥有完整身份可以备份方便后续迁移给团队其他同学。如果过期的证书下面根本没有私钥那你更要想清楚当初那张证书在谁的电脑上私钥还在不在找不到私钥的证书历史上只能选择吊销这会是后面所有坑里最麻烦的一种。2.2 把旧证书和私钥导出为.p12归档即便证书已经过期我也建议先把旧身份导出存档万一以后需要审计、追溯、找回一些历史构建的签名关系时用得上。导出方式在钥匙串里选中证书及其私钥。右键 →导出...。格式选.p12设置一个足够强度的密码。保存到一个团队内约定好的安全位置。.p12就是证书私钥的打包文件。以后任何一台Mac双击这个文件并输入密码就能把整个身份导入Keychain。团队跨机协作时拷贝的不是证书而应该是.p12——这句话我在多家公司重复过无数遍。2.3 盘点哪些描述文件还挂着旧证书证书不是单独存在的它要配合Provisioning Profile才能工作。描述文件里指定了它允许使用哪个App ID、包含哪些设备UDID、关联哪个证书。在开发者后台进入Profiles描述文件逐个查看Distribution类型的profile确认它引用的是哪张证书如果某张profile绑定了即将吊销的证书记住它的名字这一步看似简单但经常被跳过导致后来新证书建好了、Xcode还是报错因为profile里的证书信息还是旧的。3. 从吊销到重签完整更新链路3.1 第一步在开发者后台吊销旧证书登录 Apple Developer 在Certificates, Identifiers Profiles里找到过期的Distribution证书。点进证书详情选择Revoke系统会弹窗确认说明吊销后所有使用该证书的profile都会失效确认吊销这里有一个节奏问题如果你的App正处于提交审核或等待发布状态且那个构建包用的正是这张证书建议先等一下。虽然按理说Apple不会因为证书吊销把已经上传的包打回来但Post Submmission阶段的包可能遇到状态异常。稳妥做法是不要在审核关键节点动证书。项目不忙的时候慢慢换忙的时候宁可多等半天也别乱吊销。吊销完之后后台列表里这张证书会变成Revoked状态。它占用的名额会被释放你就能创建新证书了。3.2 第二步用本机钥匙串生成新的CSR创建新证书前Apple要求你提交一个CSRCertificate Signing Request证书签名请求。流程打开钥匙串访问菜单栏钥匙串访问→证书助理→从证书颁发机构请求证书填写电子邮件地址填你登录开发者账号的邮箱常用名称建议写清晰易读的名字比如2025-Apple-Distribution-Team选择存储到磁盘密钥大小保持默认2048位即可点击继续生成.certSigningRequest文件关键点这个CSR必须在将来要用来打包的那台Mac上生成。因为CSR对应的私钥会留在生成它的钥匙串里。CSR和证书是一对证书发布后只有当CSR所在机器上存在对应私钥时导入证书才算完整。如果你在A机器生成CSR却在B机器导入证书那么B机器上永远只有一个没有私钥的证书签名必然报错。如果你想团队共用新证书最理想做法是让负责构建/出包的那台主力机器生成CSR随后导出.p12分发给大家。3.3 第三步创建Apple Distribution证书并安装回Keychain回到开发者后台点击右上角的创建新证书证书类型选择Apple Distribution新版后台叫Apple Distribution旧版叫iOS Distribution功能一致上传刚才生成的.certSigningRequest生成成功后会看到一个.cer文件下载到本地双击这个.cer文件Keychain会自动把它装进登录钥匙串。安装后在钥匙串里搜索Distribution展开新证书确认下方关联了一个私钥证书状态显示This certificate is valid如果私钥没有出现别犹豫立刻去确认你生成的CSR到底是不是在当前这台电脑上做的。这是最典型的失误现场。3.4 第四步重新生成或更新所有Distribution描述文件新证书就位了现在要处理那些还引用旧证书的描述文件在开发者后台进入Profiles逐个打开类型为App Store/Ad Hoc的profile点击Edit把证书勾选为新的Distribution证书保存并重新下载.mobileprovision文件双击安装到本机/Xcode然后回到项目里如果用的是Xcode自动签名在Signing Capabilities里把Team重新选择一次触发Xcode刷新profile。如果用的是手动签名在Build Settings里确认Code Signing Identity选到了新证书同时Provisioning Profile选了更新后的描述文件。很多老项目习惯手动签名因为历史原因搞过复杂的材料链。如果你也是这样就别偷懒自动签名宁可花点时间在后台把profile刷个遍也别让Xcode自作主张给你建一堆新东西。3.5 第五步在Xcode里重新Archive并出包配置完成后在Xcode里重新Archive。期间可能遇到Xcode提示Signing for xxx requires a development team选对Team即可Xcode提示Provisioning profile xxx doesnt include signing certificate说明profile还没刷新回去后台重新下载CodeSign错误里带着证书名确认Build Settings里的签名身份没有指到旧证书Archive成功后优先用Organizer的Distribute App上传。如果上传依旧报错再把错误信息复制出来逐条对照。4. 换完证书后最容易踩的四个坑4.1 坑一证书和私钥分离了这是最常见也最难排查的。症状是钥匙串里明明能看到一张名字很新的Distribution证书但旁边没有私钥或者证书上有个黄色感叹号。排查思路私钥在哪台机器上去那台电脑打开钥匙串确认或者用security find-certificate -c Apple Distribution这种命令行方式判断最终方案导入原始.p12如果没有.p12就只能吊销新证书重新走一遍生成CSR→创建证书链路所以我还是那句话不要在没备份私钥的情况下贸然吊销。你吊销的不是一张纸而是整个签名身份。4.2 坑二推送证书过期你却在查分发证书这是两个不同世界的东西。推送证书过期时服务端调用APNs会拿到ExpiredProviderToken或BadCertificateEnvironment通知收不到但打包、上传都正常。于是很多人跑去后台一通操作把分发证书吊销了又重新生成结果推送还是坏的。正确的处理是如果服务端用的是APNs Auth Key也就是.p8它不会过期只要重新确认有效期和权限即可如果服务端用的是APNs证书.cer需要到后台重新创建一张然后在服务端替换至于什么时候两者会搞混当你在后台一句生产证书过期搜出来的资料里既有Distibution又有APNs时就会懵。记住处理打包签名问题看Distribution那张卡处理推送问题去APNs那一栏。我建议团队做巡检时把两类证书分开写清单。4.3 坑三自动签名和手动签名互相打架Xcode自动签名确实省心但一旦你项目里手动配置过描述文件它会和自动签名产生冲突报什么Multiple commands produce或者签名更改不被认可。我的实践建议老项目、手动签名坚持手动别切自动新项目、单人开发用自动签名但证书过期时先在后台吊销旧的再让Xcode自己生成新证书团队协作锁定签名方式并在.gitignore或团队文档里说明避免每次不同的人打开工程时Xcode擅自改变签名设置4.4 坑四多台电脑上新旧证书来回跳如果团队有打包机、个人开发机、CI机新旧证书会同时存在于不同电脑上。有时打包机还是旧证书你在后台吊销之后打包机上的profile指不到新证书就会莫名其妙失败。统一的铁律吊销旧证书后立刻导出新证书的.p12分发给所有需要打包的机器每台机器导入.p12确认私钥到位再逐个刷新profileCI/CD的证书安装脚本里建议加一个清理旧证书步骤用security delete-certificate或脚本批量移除已吊销证书防止Xcode在众多相同名称的证书中选错CI的坑我深有体会明明命令行里指定了CODE_SIGN_IDENTITY但Jenkins里的Keychain里同时存在两张同名证书系统挑中旧的直接报错。后来我在流水线脚本开头加了证书清理问题才彻底根除。4.5 排查口诀错误信息里的关键词对号入座错误关键词指向的问题no signing certificate钥匙串里没有可用的分发证书或私钥缺失doesnt include signing certificate描述文件没更新没绑定新证书ineligible for code signing证书与App ID不匹配或Profile类型不对iTunes Store operation failed多为证书或上传校验异常先检查Distribution证书code sign error带证书名本机存在多张同名证书或新旧证书冲突The cert has expired明确过期直接走吊销重建流程这个表格不是官方文档目录是我踩过坑以后的速查表。匹配上以后按表操作基本能在一刻钟内锁定问题。5. 收尾动作验证打包顺便给以后留后手5.1 用新证书完整跑一遍发布流程证书换了不代表就结束了你要跑完整链路验证本地xcodebuild archive成功xcodebuild -exportArchive导出ipa成功上传到App Store Connect或TestFlight成功在开发者后台检查该构建显示的状态正常如果项目配有CI/CD流水线把旧的证书和profile文件替换后完整跑一遍这一套走完才敢说证书更新完成。很多人走到第2步就以为完事了结果CI脚本里的证书路径还指着一个过期文件名上线前又白折腾一趟。5.2 建立证书到期巡检清单证书有效期常见为一年Apple在后台会明确标注到期日期。我把自己的经验整理成一份很朴素的清单每个月登录开发者后台看一眼证书列表和过期时间把Distribution、APNs Auth Key、APNs证书的到期日统一记在日历里提前30天设提醒团队内指定一个人是证书管理员其他人不要乱动后台证书新成员加入时用.p12分发身份不要让他自己再生成一套备份所有.p12和.mobileprovision的描述文件放到团队内部规范的存储目录这更像是一个运维习惯但iOS项目里证书管理员这个角色真的很重要——没人盯的话证书过期永远是夜深人静时才被发现的。5.3 归档一个团队共享的身份仓库我最后想重点说这个细节在你的私有代码仓库或团队文档区专门开一个signing/目录里面分三层certificates/*.p12所有历史证书私钥的备份文件名带上有效期profiles/*.mobileprovision所有历史描述文件按App ID和时间命名README.md记录每张证书的用途、创建人、到期日、吊销日这样无论谁接手项目都能通过README快速定位当前用的是哪张证书、下一张什么时候到期。这个习惯救过我好几次真的要安利给每一个被证书折磨过的团队。提示换完证书后别忘了检查一下你保存的.p12导出密码是否记录在案——如果团队里唯一知道密码的人休长假了你就知道什么叫证书明明在眼前签名死活过不去。
