写这篇文章是因为我当年第一次用 Cocos2d-x 给 iOS 打包时在证书和描述文件这一关卡了整整一周。那时候网上资料零散论坛里说的又都是半懂不懂的老帖子自己照着操作还是报各种签名错误最后是在折腾了不知道多少轮之后才摸清楚整套逻辑。这篇东西就是把那段时间踩过的坑、解决过的报错、以及后来给三四个项目上架走完的完整流程一次性整理出来。核心关键词是 Cocos2d-x、iOS、App Store、证书与描述文件、打包你手上如果有游戏用 Cocos2d-x 开发正打算跑真机或者提审这篇文章可以直接当操作手册用。1. Cocos2d-x 项目上架 iOS 前必须搞懂的三个概念1.1 证书苹果发给你的开发者身份证我在早期带团队做项目时发现很多从 Android 或 Web 转过来的同事第一次接触 iOS 开发最不理解的不是代码而是签名这回事。苹果的 iOS 生态是封闭的你的 App 要安装到 iPhone 上或者要上传到 App Store都必须先证明这个 App 是可信的人开发的——这个证明手段就是证书。证书的本质是一套公钥私钥机制。你本地生成一对密钥把包含公钥的证书签名请求文件.certSigningRequest简称 CSR提交给苹果苹果审核通过后给你签一个 .cer 文件。这个 .cer 文件就是你的开发者身份证。私钥留在你自己的钥匙串里它是你的私人印章不能丢不能给别人。你在 Xcode 里正式打包时用的就是这把私钥来对整个 App 进行签名。证书分两种开发证书Apple Development和发布证书Apple Distribution。开发证书用于真机调试描述文件里要绑定设备 UDID发布证书用于打包上架不需要绑定设备。很多人都会忽略的一点是证书是有有效期的开发证书和发布证书通常都是按年计算的到期前你需要在开发者后台重新生成而且旧证书一旦过期对应的描述文件也会连带失效。我见过不少项目上线一年多以后突然发不了新包一查就是证书过期没注意。1.2 描述文件Provisioning Profile把 App ID、证书、设备绑在一起的套票描述文件是 iOS 开发里误解最多的东西很多新人都把它和证书混为一谈。我从服务器开发的角度打个比方证书是数字签名者而描述文件是一张通票它把你当前的 App ID、可用的证书、可安装的设备这三样信息打包在一起苹果用这份文件告诉 iOS 系统这个 App 是允许在哪些设备上跑的。具体来说描述文件里包含三块核心信息组成要素作用说明App ID唯一标识你的 App对应 Xcode 里的 Bundle ID可以是显式 ID比如 com.example.game也可以用通配符比如 com.example.*证书和你的私钥配套的开发者身份必须是当前离线且有效的证书设备列表允许安装该 App 的设备 UDID只有开发类型的描述文件需要发布类型不需要如果你创建的是开发描述文件iOS App Development还需要把每一台测试的 iPhone、iPad 的 UDID 提前注册到开发者后台的设备列表里。发布上架用的描述文件App Store Connect不用管设备因为苹果会自己处理分发。这个区别很关键我后面会说怎么绕开这个坑。1.3 哪些操作容易陷入证书和描述文件的死循环我观察过很多 Cocos2d-x 开发者特别是喜欢在 Windows 上写代码、最后才开 Mac 打包的团队他们最常陷入这几个死循环第一用别人发过来的证书和私钥。私钥不在你本地钥匙串哪怕证书文件导入了Xcode 也会报 No signing certificate found 或者 Private key not found。第二把开发描述文件和发布描述文件的用途搞混用开发描述文件去打包上传结果在 App Store Connect 那边看到 Missing required icon file 或者直接在传包阶段报签名错误。第三Bundle ID 随意改动和前一次打包时用的不同描述文件全部作废。这类问题排查起来特别浪费时间因为报错提示往往不是Bundle ID 不匹配而是莫名其妙的签名异常、构建版本不匹配之类。2. 从头理一遍打包前的账号与后台准备工作2.1 开发者账号的选择个人还是公司Cocos2d-x 这种跨平台引擎的团队一般以几个人或者独立开发者的形态居多。苹果开发者账号主要分个人Individual和组织Organization两种都是每年 99 美元都能上架 App Store。个人账号进去以后显示的是个人名义组织账号可以显示公司名称审核上架的 App 所有权归属组织。公司账号最麻烦的一步是邓白氏编码D-U-N-S Number申请这个过程经常被卡一两周。如果你的游戏要挂公司主体、或者后面可能要开多个子账号、或者要加团队协作成员那就提前注册组织账号只是个人作品想要上架个人账号完全够用。我自己很多早期项目就是用个人账号提审的没遇到过什么限制。2.2 创建证书的完整步骤从 CSR 到 .cer很多人第一次在开发者后台点进 Certificates, Identifiers Profiles 菜单时会有点懵。这里我写一遍我惯用的创建发布证书流程照着点就行在 Mac 上打开钥匙串访问点顶部菜单证书助理 - 从证书颁发机构请求证书。在弹窗里输入你的邮箱地址常用名称可以写你的名字选择存储到磁盘点继续生成 .certSigningRequest 文件。登录 developer.apple.com/account进入 Certificates 页面点右上角的加号。在证书类型里选 Apple Distribution 或者 Apple Development继续下一步。上传刚才生成的 .certSigningRequest 文件点击生成。下载生成的 .cer 文件双击它系统会自动导入钥匙串。导入后在钥匙串的我的证书分类下应该能看到对应证书并且展开后能看到私钥一项。如果只显示证书、没有私钥说明这台电脑上没有导入私钥后续必定签名失败。我记得我自己有一次换新 Mac忘了迁移私钥结果 Archive 的时候各种报错最后老实从旧 Mac 的钥匙串导出了 .p12 文件包含证书和私钥在新 Mac 上重新导入才解决。2.3 UDID、真机调试与开发者模式如果你只是想在真机上跑跑看除了开发证书还需要把真机的 UDID 添加到开发者后台。iOS 16 之后苹果对开发模式也加了限制iOS 17 及以上版本还要在 iPhone 的设置 - 隐私与安全性 - 开发者模式里手动打开开发者模式否则 Xcode 连接真机后会提示 Developer Mode is required。获得 UDID 的方法有很多种我说一个最直观的用数据线把 iPhone 连到 Mac打开 Xcode 的 Window - Devices and Simulators选中你的设备就能看到 Identifier 这串字符复制它。然后在开发者后台的 Devices 页面点加号把设备名称和这个 UDID 填进去。接着在 Profiles 页面创建开发描述文件选择 iOS App Development关联你的 App ID、勾选刚才的证书、勾选这台设备生成并下载 .mobileprovision 文件。这里有个经验如果团队里好几个人都要跑真机不要每次都自己加设备直接让每个人注册自己的开发者子账号或者在公司账号下统一管理设备列表否则后加的设备会导致描述文件变来变去别人电脑上就会频繁出现描述文件不可用的问题。3. Cocos2d-x 工程打包 iOS 实操全流程3.1 从 Cocos2d-x 工程生成并打开 Xcode 工程Cocos2d-x 3.x 及 4.0 版本的工程目录结构里都会有一个proj.ios_mac文件夹里面放着 Xcode 工程文件。如果你的项目是在 Windows 上用 Cocos Command 工具创建的之后拷贝到 Mac 上直接用 Xcode 打开这个文件夹下的 .xcodeproj 文件即可。在这个阶段有几个细节容易出问题。第一Mac 上的 Cocos2d-x 引擎版本要和项目创建时一致如果你本地的引擎版本和项目之前的版本不一致编译时会出现各种头文件找不到、链接报错。第二如果你的 Cocos2d-x 项目用了额外的 C 源码或静态库需要确认这些文件已经添加进 Xcode 工程的相应 target 中尤其是第三方库的Header Search Paths和Library Search Paths配置。我记得有人在这里卡了好久其实问题就是工程引用路径是相对路径工程文件挪了位置后全部失效。3.2 在 Xcode 里配置 Bundle ID 和签名打开工程后点击左侧的工程名进入 TARGETS 的 Signing Capabilities 页面。这一步是整个打包流程的重头戏。先设置好 Bundle Identifier这个必须和开发者后台创建的 App ID 一致推荐格式是com.公司名.游戏名比如com.example.towerdefense。Bundle ID 一旦确定以后尽量不要改因为改动会影响后期的推送、游戏中心、内购等能力的关联。然后勾选 Automatically manage signing选择你的 Team。Xcode 的自动签名模式会帮你自动创建/匹配描述文件个人开发者账号通常几秒钟就能完成。但我得提醒一句Cocos2d-x 老项目的 target 配置往往比较古老自动签名有时候会失败报 Failed to create provisioning profile 这种提示。遇到这种情况我的做法是取消自动签名改用手动管理在开发者后台把 App ID、描述文件都建好然后在 Xcode 的 Provisioning Profile 里选择对应的 .mobileprovision 文件。手动模式虽然麻烦但比较可控尤其在多 target、扩展模块比如通知扩展并存的情况下自动签名反而容易乱配。提示不管自动还是手动最终的 Archive 包签名使用的都是你本地钥匙串里的发布证书。我建议在打包前先确认一次钥匙串状态避免打包到一半发现私钥丢失。3.3 图标、启动屏和权限提示的配置App Store 对图标和启动屏有硬性要求这一块 Cocos2d-x 的默认模板通常是不完整的。你需要打开 Assets.xcassets找到 AppIcon把各个尺寸的图标拖进去。如果你手里只有一张大图可以用工具裁剪生成所有尺寸。图标必须是不透明的 PNG不要带圆角系统会帮你切圆角。启动屏优先用 LaunchScreen.storyboardCocos2d-x 的模板一般自带一个把背景颜色改成你的游戏主色调或者把启动图做成带 Logo 的图片视图。需要注意如果你的 App 支持横竖屏切换启动屏最好用安全区域内居中显示否则会在真机上发现多出的黑边。权限配置集中在 Info.plist 里。如果你的游戏用了相机、相册、麦克风、定位这些能力必须添加对应的使用说明文案比如 NSCameraUsageDescription 填一句需要使用相机以进行玩家头像上传。苹果审核很看重这个缺失的话会被直接拒绝而且审核员给的拒绝理由通常会让你一头雾水我第一次遇到就是因为没写相册权限描述被以 2.1 的 App Completeness 拒了。3.4 真机跑通模拟器能跑不代表真机没问题在正式打包前我强烈建议先把工程跑一遍真机。切换到真机调试签名开发证书开发描述文件选择你的设备作为运行目标然后 CommandR。这个步骤能帮你过滤掉大量后面提审才会暴露的问题。真机跑不通的常见情况有三种第一种签名配置没问题但 Xcode 提示 Could not find Developer Disk Image这是 Xcode 版本和真机 iOS 版本不匹配导致的升级 Xcode 或降低真机系统版本可以解决。第二种编译通过了但一启动就闪退这种问题多半是内存占用过高或者用了不支持的 API可以用真机日志过滤 exception 关键字来定位。第三种Cocos2d-x 的某些 effect 或 shader 在模拟器上表现正常但真机上帧率骤降或者黑屏这属于引擎渲染细节差异跑真机这一步就是用来提前发现这些问题的。3.5 Archive 打包从开发包到 ipa 的临门一脚真机调试通过之后就要正式打包了。先在 Xcode 顶部的 Scheme 设备选择器里把运行目标选成 Any iOS Device (arm64)注意不能是模拟器。然后点菜单 Product - ArchiveXcode 会开始编译并生成归档包。这一步通常会持续几分钟到十几分钟取决于工程大小。Archive 完成后Xcode 会弹出 Organizer 窗口在列表里可以看到刚才生成的包版本号、Build 号、时间。点击右边的 Distribute App会进入导出选项导出选项适用场景说明App Store Connect提交上架生成上传到 App Store Connect 的 ipa 包Ad Hoc测试分发打到已注册的测试设备不经过 App StoreDevelopment开发调试给开发设备用的包功能和 Ad Hoc 类似选 App Store Connect然后选择 Upload 直接上传或者选择 Export 导出 ipa 文件后续再用 Transporter 上传。早期我习惯直接在 Organizer 里上传后来发现在弱网环境下 Organizer 上传经常莫名其妙中断换成导出成 ipa、再用 Transporter 上传就稳定很多。4. 上传到 App Store Connect 和提审流程4.1 在 App Store Connect 创建 App 记录在打 ipa 之前或之后你都需要先登录 appstoreconnect.apple.com进入我的 App点左上角加号选择新建 App。这里要填的 Bundle ID 必须和 Xcode 工程里的一致否则上传后无法关联到这个 App 记录。新 App 记录里要填一堆信息主要语言、应用名称、套装 ID、SKU。套装 ID 就是你刚才的 Bundle IDSKU 是你内部使用的唯一代码比如example.towerdefense.001用字母、数字、短横线组合。我建议在填这些信息之前先把 App 名称想好因为苹果对名称有 30 个字符的限制并且不能和已有应用名冲突重名审核时会让你改名那会多耽误一轮时间。信息填完以后建议立刻把App 信息页里的类目选好参考的关键词填好隐私政策网址准备好。Cocos2d-x 开发的游戏大多归在游戏类目子类目按照类型选。隐私政策尤其重要如果你的 App 有账号体系、收集任何用户行为数据或者接入了广告 SDK隐私政策链接必须可用否则提交后会被以 5.1.1 数据收集条款打回。4.2 用 Transporter 上传 ipa 的实操如果你选择在 Organizer 里直接 Upload这一步可以跳过如果你用我推荐的导出 ipa 方案那就打开 Mac App Store 里的Transporter应用登录你的开发者账号把 ipa 文件拖进窗口点击交付。Transporter 会先进行本地校验校验通过后开始上传上传完成后会显示已交付然后等待 App Store Connect 处理。通常处理时间在几分钟到半小时之间。之后打开 App Store Connect 的TestFlight页面可以看到上传的构建版本。这里有个很重要的细节刚上传的构建版本要等几分钟才能显示刷新几次看不到很正常不要急着重复上传相同构建号。苹果不允许两个构建号相同的 ipa 反复上传如果你想修 bug 重新传必须把 Xcode 工程里的 CURRENT_PROJECT_VERSIONBuild 号增大否则会报 Invalid Build Number 或者直接显示为 已删除。在 TestFlight 里能看到构建版本以后我建议先把它添加到测试组用 TestFlight 做一轮内部测试。这一步虽然多花点时间但等于在真实审核前先自己走一遍安装流程还能拿到崩溃日志对审核通过率帮助极大。4.3 提审前必须检查的几件事提交审核的入口是 App Store Connect 的版本页面选择你上传好的构建版本填写应用描述、更新日志、关键词、版权信息上传 6.5 英寸和 5.5 英寸的截图设定价格和销售范围然后点添加以供审核。审核被拒的前几名原因我列一个自己遇到过的清单审核员打开的页面或游戏内有无法跳过的弹窗或恢复购买按钮无效。这类属于 2.1 App 完成度问题。游戏素材、名称、截图里包含第三方版权角色、商标或明显的蹭热度内容属于 5.2.1 知识产权问题。需要登录但没有提供审核专用的演示账号属于 2.1 / 5.2.1 的常见拦截项。接入了广告但没有正确的数据披露或者没有允许用户关闭个性化广告涉及 5.1.1。应用在审核环境下崩溃属于 2.1 / 2.3.7 崩溃问题。这个问题在 Cocos2d-x 游戏里经常和内存占用过高、启动加载资源过大有关。提审前我习惯做的事用真机断开网络用飞行模式冷启动一次看有没有崩溃然后再切换网络、切换 WiFi / 蜂窝再冷启动一次。这两个场景能把很大一部分审核环境下的崩溃问题提前暴露出来。5. 证书与描述文件高频问题速查与避坑指南5.1 证书无效、证书过期、证书被吊销检查证书是否有效的方式打开钥匙串访问找到对应证书看状态是否为此证书有效以及有效期是否在范围内。如果有次证书显示 此证书已失效那基本是证书被吊销了比如更换了开发者后台里的证书或者账号异常。实际排查顺序是Xcode 的 Signing Capabilities 页面是否报红钥匙串里的证书私钥是否完整开发者后台的证书和描述文件是否在有效期内最后再把本地过期的描述文件全部删除重新下载。很多签名问题的根源不是后台配置错了而是本地钥匙串里持有多个同名旧证书Xcode 选错了导致后面一系列报错。我可以给你一个下策中的上策把钥匙串里所有和开发者账号相关的旧证书先归档或删除在开发者后台重新下载需要的证书并安装让 Xcode 只有一个选择。5.2 Provisioning profile doesnt include signing certificate 报错这个报错通常意味着你在 Xcode 里选择的描述文件和当前使用的证书不是同一套。比如描述文件里安装的是 A 证书但钥匙串里 B 证书仍然有效而 Xcode 自动选择了 B于是签名校验失败。解决办法是进入 Xcode 的 Build Settings 页面搜索 Provisioning Profile选择对应描述文件同时搜索 Code Signing Identity选择合适证书确保两者匹配。我遇到这种问题最有效的清理方法先在开发者后台把描述文件重新下载一遍双击安装到 Xcode然后在 Xcode 里面把旧的签名配置删掉重新选择让构建系统使用新的一份。5.3 Unable to create provisioning profile 自动签名失败如果在自动签名模式下点击Refresh Provisioning Profiles失败先检查 App ID 是否已在开发者后台创建过Bundle ID 是否因为特殊字符导致无法识别。另外如果账号里没有iOS App Development类型的证书自动签名也会失败。这时候到开发者后台的 Certificates 页面确认证书是否存在如果不存在创建一个然后回到 Xcode 重新刷新。很多 Cocos2d-x 工程默认的 Bundle ID 是com.game.game这种看起来不太正规的 ID这类 ID 在创建 App ID 时可以使用但如果你之前已经在开发者后台里手动创建过相同 ID 的 App ID自动签名反而会被挡住。我在实际操作中会把这类项目简化为开发者后台手动创建好 App ID - 手动创建描述文件 - Xcode 关闭自动签名 - 手动选取一套下来最省心。5.4 Xcode 编译时报 CodeSign error: Certificate identity appeared twice这个问题我在多人协作的工程里见过好几次。原因是钥匙串里存在多个相同名称的证书或同一个证书被安装了多份导致签名时无法确定用哪一个。打开钥匙串把重复的证书删掉只留最新的一份然后清理 DerivedData重新编译即可。5.5 审核被拒后重新在本地打包时提示 Account has no permission这个提示通常不是因为你的账号没有权限而是本地的 Xcode 登录状态和开发者后台的证书信息不是最新版比如团队成员被移除、账号权限变了。去 Xcode 的 Settings - Accounts 里移除账号重新添加一次然后再刷新签名。如果还不行检查开发者后台里是否被移出了团队很多个人开发者都忽略了自己账号被设为App 管理角色而不是管理员角色时只能管理部分功能。5.6 老项目在升级 Xcode 后突然出现了 Multiple commands produce 报错这虽然不直接是证书问题但 Cocos2d-x 老项目升级 Xcode 后太常见了而且它导致的最终报错看起来和打包签名很像。核心原因是新版 Xcode 的 Build System 对重复文件更严格我在项目里遇到的是 Info.plist 被重复打包。解决办法是到 Build Phases 的 Copy Bundle Resources 里把 Info.plist 那一条删除因为 Info.plist 在 Build Settings 里已经配置过了不需要再被复制进资源目录。6. 最后再分享一点个人经验从我接手过的 Cocos2d-x 项目来看iOS 打包和上架这件事本身并不难难的是概念不清时反复试错的时间成本。证书描述文件的坑往往不是因为你不会点鼠标而是因为这些机制藏在苹果后台的各个角落平时用不到就完全陌生。所以我的建议很直接不管你的项目多小都走一遍真机调试 - TestFlight - 提审的完整流程第一次跑通以后后面换项目就是复制粘贴的事。另外一定要做好密钥和证书的备份。把 .cer 证书、.p12 私钥、开发者后台里的描述文件以及他们的有效期整理到一张表里每次过年前检查一遍差不多到期前一个多月就续期。别指望一次配好就什么都不管了苹果的证书体系天生就是需要定期维护的早做准备总比上架前发现证书过期要好得多。希望这篇东西能帮你少走点弯路尤其是那些我当年一个个试出来的报错和绕坑办法你照着做应该两天内就能把包安安稳稳送审。
Cocos2d-x iOS打包上架指南：证书与描述文件配置全攻略
写这篇文章是因为我当年第一次用 Cocos2d-x 给 iOS 打包时在证书和描述文件这一关卡了整整一周。那时候网上资料零散论坛里说的又都是半懂不懂的老帖子自己照着操作还是报各种签名错误最后是在折腾了不知道多少轮之后才摸清楚整套逻辑。这篇东西就是把那段时间踩过的坑、解决过的报错、以及后来给三四个项目上架走完的完整流程一次性整理出来。核心关键词是 Cocos2d-x、iOS、App Store、证书与描述文件、打包你手上如果有游戏用 Cocos2d-x 开发正打算跑真机或者提审这篇文章可以直接当操作手册用。1. Cocos2d-x 项目上架 iOS 前必须搞懂的三个概念1.1 证书苹果发给你的开发者身份证我在早期带团队做项目时发现很多从 Android 或 Web 转过来的同事第一次接触 iOS 开发最不理解的不是代码而是签名这回事。苹果的 iOS 生态是封闭的你的 App 要安装到 iPhone 上或者要上传到 App Store都必须先证明这个 App 是可信的人开发的——这个证明手段就是证书。证书的本质是一套公钥私钥机制。你本地生成一对密钥把包含公钥的证书签名请求文件.certSigningRequest简称 CSR提交给苹果苹果审核通过后给你签一个 .cer 文件。这个 .cer 文件就是你的开发者身份证。私钥留在你自己的钥匙串里它是你的私人印章不能丢不能给别人。你在 Xcode 里正式打包时用的就是这把私钥来对整个 App 进行签名。证书分两种开发证书Apple Development和发布证书Apple Distribution。开发证书用于真机调试描述文件里要绑定设备 UDID发布证书用于打包上架不需要绑定设备。很多人都会忽略的一点是证书是有有效期的开发证书和发布证书通常都是按年计算的到期前你需要在开发者后台重新生成而且旧证书一旦过期对应的描述文件也会连带失效。我见过不少项目上线一年多以后突然发不了新包一查就是证书过期没注意。1.2 描述文件Provisioning Profile把 App ID、证书、设备绑在一起的套票描述文件是 iOS 开发里误解最多的东西很多新人都把它和证书混为一谈。我从服务器开发的角度打个比方证书是数字签名者而描述文件是一张通票它把你当前的 App ID、可用的证书、可安装的设备这三样信息打包在一起苹果用这份文件告诉 iOS 系统这个 App 是允许在哪些设备上跑的。具体来说描述文件里包含三块核心信息组成要素作用说明App ID唯一标识你的 App对应 Xcode 里的 Bundle ID可以是显式 ID比如 com.example.game也可以用通配符比如 com.example.*证书和你的私钥配套的开发者身份必须是当前离线且有效的证书设备列表允许安装该 App 的设备 UDID只有开发类型的描述文件需要发布类型不需要如果你创建的是开发描述文件iOS App Development还需要把每一台测试的 iPhone、iPad 的 UDID 提前注册到开发者后台的设备列表里。发布上架用的描述文件App Store Connect不用管设备因为苹果会自己处理分发。这个区别很关键我后面会说怎么绕开这个坑。1.3 哪些操作容易陷入证书和描述文件的死循环我观察过很多 Cocos2d-x 开发者特别是喜欢在 Windows 上写代码、最后才开 Mac 打包的团队他们最常陷入这几个死循环第一用别人发过来的证书和私钥。私钥不在你本地钥匙串哪怕证书文件导入了Xcode 也会报 No signing certificate found 或者 Private key not found。第二把开发描述文件和发布描述文件的用途搞混用开发描述文件去打包上传结果在 App Store Connect 那边看到 Missing required icon file 或者直接在传包阶段报签名错误。第三Bundle ID 随意改动和前一次打包时用的不同描述文件全部作废。这类问题排查起来特别浪费时间因为报错提示往往不是Bundle ID 不匹配而是莫名其妙的签名异常、构建版本不匹配之类。2. 从头理一遍打包前的账号与后台准备工作2.1 开发者账号的选择个人还是公司Cocos2d-x 这种跨平台引擎的团队一般以几个人或者独立开发者的形态居多。苹果开发者账号主要分个人Individual和组织Organization两种都是每年 99 美元都能上架 App Store。个人账号进去以后显示的是个人名义组织账号可以显示公司名称审核上架的 App 所有权归属组织。公司账号最麻烦的一步是邓白氏编码D-U-N-S Number申请这个过程经常被卡一两周。如果你的游戏要挂公司主体、或者后面可能要开多个子账号、或者要加团队协作成员那就提前注册组织账号只是个人作品想要上架个人账号完全够用。我自己很多早期项目就是用个人账号提审的没遇到过什么限制。2.2 创建证书的完整步骤从 CSR 到 .cer很多人第一次在开发者后台点进 Certificates, Identifiers Profiles 菜单时会有点懵。这里我写一遍我惯用的创建发布证书流程照着点就行在 Mac 上打开钥匙串访问点顶部菜单证书助理 - 从证书颁发机构请求证书。在弹窗里输入你的邮箱地址常用名称可以写你的名字选择存储到磁盘点继续生成 .certSigningRequest 文件。登录 developer.apple.com/account进入 Certificates 页面点右上角的加号。在证书类型里选 Apple Distribution 或者 Apple Development继续下一步。上传刚才生成的 .certSigningRequest 文件点击生成。下载生成的 .cer 文件双击它系统会自动导入钥匙串。导入后在钥匙串的我的证书分类下应该能看到对应证书并且展开后能看到私钥一项。如果只显示证书、没有私钥说明这台电脑上没有导入私钥后续必定签名失败。我记得我自己有一次换新 Mac忘了迁移私钥结果 Archive 的时候各种报错最后老实从旧 Mac 的钥匙串导出了 .p12 文件包含证书和私钥在新 Mac 上重新导入才解决。2.3 UDID、真机调试与开发者模式如果你只是想在真机上跑跑看除了开发证书还需要把真机的 UDID 添加到开发者后台。iOS 16 之后苹果对开发模式也加了限制iOS 17 及以上版本还要在 iPhone 的设置 - 隐私与安全性 - 开发者模式里手动打开开发者模式否则 Xcode 连接真机后会提示 Developer Mode is required。获得 UDID 的方法有很多种我说一个最直观的用数据线把 iPhone 连到 Mac打开 Xcode 的 Window - Devices and Simulators选中你的设备就能看到 Identifier 这串字符复制它。然后在开发者后台的 Devices 页面点加号把设备名称和这个 UDID 填进去。接着在 Profiles 页面创建开发描述文件选择 iOS App Development关联你的 App ID、勾选刚才的证书、勾选这台设备生成并下载 .mobileprovision 文件。这里有个经验如果团队里好几个人都要跑真机不要每次都自己加设备直接让每个人注册自己的开发者子账号或者在公司账号下统一管理设备列表否则后加的设备会导致描述文件变来变去别人电脑上就会频繁出现描述文件不可用的问题。3. Cocos2d-x 工程打包 iOS 实操全流程3.1 从 Cocos2d-x 工程生成并打开 Xcode 工程Cocos2d-x 3.x 及 4.0 版本的工程目录结构里都会有一个proj.ios_mac文件夹里面放着 Xcode 工程文件。如果你的项目是在 Windows 上用 Cocos Command 工具创建的之后拷贝到 Mac 上直接用 Xcode 打开这个文件夹下的 .xcodeproj 文件即可。在这个阶段有几个细节容易出问题。第一Mac 上的 Cocos2d-x 引擎版本要和项目创建时一致如果你本地的引擎版本和项目之前的版本不一致编译时会出现各种头文件找不到、链接报错。第二如果你的 Cocos2d-x 项目用了额外的 C 源码或静态库需要确认这些文件已经添加进 Xcode 工程的相应 target 中尤其是第三方库的Header Search Paths和Library Search Paths配置。我记得有人在这里卡了好久其实问题就是工程引用路径是相对路径工程文件挪了位置后全部失效。3.2 在 Xcode 里配置 Bundle ID 和签名打开工程后点击左侧的工程名进入 TARGETS 的 Signing Capabilities 页面。这一步是整个打包流程的重头戏。先设置好 Bundle Identifier这个必须和开发者后台创建的 App ID 一致推荐格式是com.公司名.游戏名比如com.example.towerdefense。Bundle ID 一旦确定以后尽量不要改因为改动会影响后期的推送、游戏中心、内购等能力的关联。然后勾选 Automatically manage signing选择你的 Team。Xcode 的自动签名模式会帮你自动创建/匹配描述文件个人开发者账号通常几秒钟就能完成。但我得提醒一句Cocos2d-x 老项目的 target 配置往往比较古老自动签名有时候会失败报 Failed to create provisioning profile 这种提示。遇到这种情况我的做法是取消自动签名改用手动管理在开发者后台把 App ID、描述文件都建好然后在 Xcode 的 Provisioning Profile 里选择对应的 .mobileprovision 文件。手动模式虽然麻烦但比较可控尤其在多 target、扩展模块比如通知扩展并存的情况下自动签名反而容易乱配。提示不管自动还是手动最终的 Archive 包签名使用的都是你本地钥匙串里的发布证书。我建议在打包前先确认一次钥匙串状态避免打包到一半发现私钥丢失。3.3 图标、启动屏和权限提示的配置App Store 对图标和启动屏有硬性要求这一块 Cocos2d-x 的默认模板通常是不完整的。你需要打开 Assets.xcassets找到 AppIcon把各个尺寸的图标拖进去。如果你手里只有一张大图可以用工具裁剪生成所有尺寸。图标必须是不透明的 PNG不要带圆角系统会帮你切圆角。启动屏优先用 LaunchScreen.storyboardCocos2d-x 的模板一般自带一个把背景颜色改成你的游戏主色调或者把启动图做成带 Logo 的图片视图。需要注意如果你的 App 支持横竖屏切换启动屏最好用安全区域内居中显示否则会在真机上发现多出的黑边。权限配置集中在 Info.plist 里。如果你的游戏用了相机、相册、麦克风、定位这些能力必须添加对应的使用说明文案比如 NSCameraUsageDescription 填一句需要使用相机以进行玩家头像上传。苹果审核很看重这个缺失的话会被直接拒绝而且审核员给的拒绝理由通常会让你一头雾水我第一次遇到就是因为没写相册权限描述被以 2.1 的 App Completeness 拒了。3.4 真机跑通模拟器能跑不代表真机没问题在正式打包前我强烈建议先把工程跑一遍真机。切换到真机调试签名开发证书开发描述文件选择你的设备作为运行目标然后 CommandR。这个步骤能帮你过滤掉大量后面提审才会暴露的问题。真机跑不通的常见情况有三种第一种签名配置没问题但 Xcode 提示 Could not find Developer Disk Image这是 Xcode 版本和真机 iOS 版本不匹配导致的升级 Xcode 或降低真机系统版本可以解决。第二种编译通过了但一启动就闪退这种问题多半是内存占用过高或者用了不支持的 API可以用真机日志过滤 exception 关键字来定位。第三种Cocos2d-x 的某些 effect 或 shader 在模拟器上表现正常但真机上帧率骤降或者黑屏这属于引擎渲染细节差异跑真机这一步就是用来提前发现这些问题的。3.5 Archive 打包从开发包到 ipa 的临门一脚真机调试通过之后就要正式打包了。先在 Xcode 顶部的 Scheme 设备选择器里把运行目标选成 Any iOS Device (arm64)注意不能是模拟器。然后点菜单 Product - ArchiveXcode 会开始编译并生成归档包。这一步通常会持续几分钟到十几分钟取决于工程大小。Archive 完成后Xcode 会弹出 Organizer 窗口在列表里可以看到刚才生成的包版本号、Build 号、时间。点击右边的 Distribute App会进入导出选项导出选项适用场景说明App Store Connect提交上架生成上传到 App Store Connect 的 ipa 包Ad Hoc测试分发打到已注册的测试设备不经过 App StoreDevelopment开发调试给开发设备用的包功能和 Ad Hoc 类似选 App Store Connect然后选择 Upload 直接上传或者选择 Export 导出 ipa 文件后续再用 Transporter 上传。早期我习惯直接在 Organizer 里上传后来发现在弱网环境下 Organizer 上传经常莫名其妙中断换成导出成 ipa、再用 Transporter 上传就稳定很多。4. 上传到 App Store Connect 和提审流程4.1 在 App Store Connect 创建 App 记录在打 ipa 之前或之后你都需要先登录 appstoreconnect.apple.com进入我的 App点左上角加号选择新建 App。这里要填的 Bundle ID 必须和 Xcode 工程里的一致否则上传后无法关联到这个 App 记录。新 App 记录里要填一堆信息主要语言、应用名称、套装 ID、SKU。套装 ID 就是你刚才的 Bundle IDSKU 是你内部使用的唯一代码比如example.towerdefense.001用字母、数字、短横线组合。我建议在填这些信息之前先把 App 名称想好因为苹果对名称有 30 个字符的限制并且不能和已有应用名冲突重名审核时会让你改名那会多耽误一轮时间。信息填完以后建议立刻把App 信息页里的类目选好参考的关键词填好隐私政策网址准备好。Cocos2d-x 开发的游戏大多归在游戏类目子类目按照类型选。隐私政策尤其重要如果你的 App 有账号体系、收集任何用户行为数据或者接入了广告 SDK隐私政策链接必须可用否则提交后会被以 5.1.1 数据收集条款打回。4.2 用 Transporter 上传 ipa 的实操如果你选择在 Organizer 里直接 Upload这一步可以跳过如果你用我推荐的导出 ipa 方案那就打开 Mac App Store 里的Transporter应用登录你的开发者账号把 ipa 文件拖进窗口点击交付。Transporter 会先进行本地校验校验通过后开始上传上传完成后会显示已交付然后等待 App Store Connect 处理。通常处理时间在几分钟到半小时之间。之后打开 App Store Connect 的TestFlight页面可以看到上传的构建版本。这里有个很重要的细节刚上传的构建版本要等几分钟才能显示刷新几次看不到很正常不要急着重复上传相同构建号。苹果不允许两个构建号相同的 ipa 反复上传如果你想修 bug 重新传必须把 Xcode 工程里的 CURRENT_PROJECT_VERSIONBuild 号增大否则会报 Invalid Build Number 或者直接显示为 已删除。在 TestFlight 里能看到构建版本以后我建议先把它添加到测试组用 TestFlight 做一轮内部测试。这一步虽然多花点时间但等于在真实审核前先自己走一遍安装流程还能拿到崩溃日志对审核通过率帮助极大。4.3 提审前必须检查的几件事提交审核的入口是 App Store Connect 的版本页面选择你上传好的构建版本填写应用描述、更新日志、关键词、版权信息上传 6.5 英寸和 5.5 英寸的截图设定价格和销售范围然后点添加以供审核。审核被拒的前几名原因我列一个自己遇到过的清单审核员打开的页面或游戏内有无法跳过的弹窗或恢复购买按钮无效。这类属于 2.1 App 完成度问题。游戏素材、名称、截图里包含第三方版权角色、商标或明显的蹭热度内容属于 5.2.1 知识产权问题。需要登录但没有提供审核专用的演示账号属于 2.1 / 5.2.1 的常见拦截项。接入了广告但没有正确的数据披露或者没有允许用户关闭个性化广告涉及 5.1.1。应用在审核环境下崩溃属于 2.1 / 2.3.7 崩溃问题。这个问题在 Cocos2d-x 游戏里经常和内存占用过高、启动加载资源过大有关。提审前我习惯做的事用真机断开网络用飞行模式冷启动一次看有没有崩溃然后再切换网络、切换 WiFi / 蜂窝再冷启动一次。这两个场景能把很大一部分审核环境下的崩溃问题提前暴露出来。5. 证书与描述文件高频问题速查与避坑指南5.1 证书无效、证书过期、证书被吊销检查证书是否有效的方式打开钥匙串访问找到对应证书看状态是否为此证书有效以及有效期是否在范围内。如果有次证书显示 此证书已失效那基本是证书被吊销了比如更换了开发者后台里的证书或者账号异常。实际排查顺序是Xcode 的 Signing Capabilities 页面是否报红钥匙串里的证书私钥是否完整开发者后台的证书和描述文件是否在有效期内最后再把本地过期的描述文件全部删除重新下载。很多签名问题的根源不是后台配置错了而是本地钥匙串里持有多个同名旧证书Xcode 选错了导致后面一系列报错。我可以给你一个下策中的上策把钥匙串里所有和开发者账号相关的旧证书先归档或删除在开发者后台重新下载需要的证书并安装让 Xcode 只有一个选择。5.2 Provisioning profile doesnt include signing certificate 报错这个报错通常意味着你在 Xcode 里选择的描述文件和当前使用的证书不是同一套。比如描述文件里安装的是 A 证书但钥匙串里 B 证书仍然有效而 Xcode 自动选择了 B于是签名校验失败。解决办法是进入 Xcode 的 Build Settings 页面搜索 Provisioning Profile选择对应描述文件同时搜索 Code Signing Identity选择合适证书确保两者匹配。我遇到这种问题最有效的清理方法先在开发者后台把描述文件重新下载一遍双击安装到 Xcode然后在 Xcode 里面把旧的签名配置删掉重新选择让构建系统使用新的一份。5.3 Unable to create provisioning profile 自动签名失败如果在自动签名模式下点击Refresh Provisioning Profiles失败先检查 App ID 是否已在开发者后台创建过Bundle ID 是否因为特殊字符导致无法识别。另外如果账号里没有iOS App Development类型的证书自动签名也会失败。这时候到开发者后台的 Certificates 页面确认证书是否存在如果不存在创建一个然后回到 Xcode 重新刷新。很多 Cocos2d-x 工程默认的 Bundle ID 是com.game.game这种看起来不太正规的 ID这类 ID 在创建 App ID 时可以使用但如果你之前已经在开发者后台里手动创建过相同 ID 的 App ID自动签名反而会被挡住。我在实际操作中会把这类项目简化为开发者后台手动创建好 App ID - 手动创建描述文件 - Xcode 关闭自动签名 - 手动选取一套下来最省心。5.4 Xcode 编译时报 CodeSign error: Certificate identity appeared twice这个问题我在多人协作的工程里见过好几次。原因是钥匙串里存在多个相同名称的证书或同一个证书被安装了多份导致签名时无法确定用哪一个。打开钥匙串把重复的证书删掉只留最新的一份然后清理 DerivedData重新编译即可。5.5 审核被拒后重新在本地打包时提示 Account has no permission这个提示通常不是因为你的账号没有权限而是本地的 Xcode 登录状态和开发者后台的证书信息不是最新版比如团队成员被移除、账号权限变了。去 Xcode 的 Settings - Accounts 里移除账号重新添加一次然后再刷新签名。如果还不行检查开发者后台里是否被移出了团队很多个人开发者都忽略了自己账号被设为App 管理角色而不是管理员角色时只能管理部分功能。5.6 老项目在升级 Xcode 后突然出现了 Multiple commands produce 报错这虽然不直接是证书问题但 Cocos2d-x 老项目升级 Xcode 后太常见了而且它导致的最终报错看起来和打包签名很像。核心原因是新版 Xcode 的 Build System 对重复文件更严格我在项目里遇到的是 Info.plist 被重复打包。解决办法是到 Build Phases 的 Copy Bundle Resources 里把 Info.plist 那一条删除因为 Info.plist 在 Build Settings 里已经配置过了不需要再被复制进资源目录。6. 最后再分享一点个人经验从我接手过的 Cocos2d-x 项目来看iOS 打包和上架这件事本身并不难难的是概念不清时反复试错的时间成本。证书描述文件的坑往往不是因为你不会点鼠标而是因为这些机制藏在苹果后台的各个角落平时用不到就完全陌生。所以我的建议很直接不管你的项目多小都走一遍真机调试 - TestFlight - 提审的完整流程第一次跑通以后后面换项目就是复制粘贴的事。另外一定要做好密钥和证书的备份。把 .cer 证书、.p12 私钥、开发者后台里的描述文件以及他们的有效期整理到一张表里每次过年前检查一遍差不多到期前一个多月就续期。别指望一次配好就什么都不管了苹果的证书体系天生就是需要定期维护的早做准备总比上架前发现证书过期要好得多。希望这篇东西能帮你少走点弯路尤其是那些我当年一个个试出来的报错和绕坑办法你照着做应该两天内就能把包安安稳稳送审。
