跳到主要内容
教程目录

在 Windows 上申请 iOS 开发证书、描述文件和 p12

iOS App 装到手机和上架都要签名，签名需要证书（.p12）和描述文件（.mobileprovision）。Apple 官方的申请流程要在 Mac 的「钥匙串访问」里生成 CSR，本文用 OpenSSL 在 Windows 上完成同样的事，从生成私钥一直做到 KXBuild 能用这些文件签名。需要准备已加入 Apple Developer Program 的账号、一台 iPhone 和数据线，整个过程大约二十分钟。

KXBuild 不会替你在 Apple 后台创建证书，它只读取你放进证书目录的文件。除了本文的 OpenSSL 做法，也可以用 Appuploader 这类工具登录开发者账号直接生成，见证书与签名。

先分清要申请哪些

证书 什么时候用 配合的描述文件
Apple Development 装到自己的测试机上运行、断点调试 iOS App Development，要包含设备 UDID
Apple Distribution 上传 App Store Connect、TestFlight，或打 Ad Hoc 包发给测试人员 App Store Connect，或 Ad Hoc（要包含设备 UDID）

刚开始开发只需要 Apple Development 证书和一份 Development 描述文件，准备上架时再申请 Apple Distribution。两类证书的申请步骤完全一样，下文以开发证书为例。

证书有效期一年。一个团队的发布证书数量有上限，团队成员之间应当共用同一张发布证书，而不是每人申请一张；开发证书可以每人一张。

用 OpenSSL 生成私钥和 CSR

CSR（证书签名请求）包含你的公钥，交给 Apple 签发证书；对应的私钥留在本机，之后合成 .p12 要用。

Windows 没有自带 OpenSSL，装了 Git for Windows 的已经有一份，位置是 C:\Program Files\Git\mingw64\bin\openssl.exe。下面的命令在 PowerShell 中执行，先把它存进一个变量。没有装 Git 的，也可以用 winget 或其他渠道安装 OpenSSL，把 & $openssl 换成 openssl 即可。

1$openssl = "C:\Program Files\Git\mingw64\bin\openssl.exe"
2mkdir D:\ios-cert; cd D:\ios-cert
3& $openssl req -new -newkey rsa:2048 -nodes -keyout ios.key -out ios.csr -subj "/emailAddress=you@example.com/CN=Your Name/C=CN"

emailAddress 和 CN 换成你的邮箱和名字，Apple 签发证书时会用账号上的团队信息，这里的值只影响 CSR 本身。执行后目录里得到两个文件，ios.key 是私钥，ios.csr 是要上传的请求。

在 Git Bash 中执行同样的命令时，以 / 开头的 -subj 参数会被当成路径改写，命令前加 MSYS_NO_PATHCONV=1 可以避免。在 PowerShell 中执行没有这个问题。

ios.key 必须妥善保管。 丢了私钥，这张证书就不能再签名，只能吊销后重新申请。

上传 CSR 下载证书

  1. 登录 developer.apple.com，进入 Certificates, Identifiers & Profiles，打开 Certificates 页，点加号。
  2. 选择 Apple Development（发布证书选 Apple Distribution），点 Continue。
  3. 上传 ios.csr，点 Continue。
  4. 点 Download，得到 development.cer（发布证书下载后通常叫 distribution.cer）。

下载的 .cer 是 DER 格式，只含证书，不含私钥，单独拿它不能签名。

合成 p12

先把 .cer 转成 PEM 格式，再和私钥合成 .p12。第二条命令会让你输入两次导出密码，这个密码之后要写进 password.properties。

1& $openssl x509 -in development.cer -inform DER -out development.pem
2& $openssl pkcs12 -export -inkey ios.key -in development.pem -out development.p12

Git for Windows 自带的是 OpenSSL 3，默认用 AES-256 加密 .p12，KXBuild 可以直接读取。同一个文件还要导入 Mac 的钥匙串或其他较老的签名工具时，它们可能报密码错误，这时加上 -legacy 重新导出一份兼容格式。

1& $openssl pkcs12 -export -legacy -inkey ios.key -in development.pem -out development.p12

可以用下面的命令确认 .p12 里同时有证书和私钥，输出中能看到 Certificate bag 和 Shrouded Keybag 两行即可。

1& $openssl pkcs12 -in development.p12 -info -noout

注册 App ID

在 Identifiers 页点加号，选 App IDs → App，填写描述和 Bundle ID。

  • Explicit（精确） 填完整的 Bundle ID，如 com.example.myapp，和工程里的 PRODUCT_BUNDLE_IDENTIFIER 一致。要用推送、iCloud、Sign in with Apple、App Groups 等能力必须选这种，并在下方 Capabilities 里勾选。
  • Wildcard（通配） 如 com.example.*，一个描述文件覆盖多个 App 和扩展，只适合开发阶段、没有用到上述能力的工程。

工程里有 Widget、通知扩展等扩展 target 的，每个扩展的 Bundle ID（如 com.example.myapp.widget）也要各注册一个 App ID。工程中各 target 的 Bundle ID 可以用 kxbuild project info .\MyApp.xcodeproj 查看。

添加测试设备

Development 和 Ad Hoc 描述文件只允许安装到注册过的设备，先拿到手机的 UDID。

用数据线把 iPhone 连到电脑，解锁并点「信任此电脑」，然后运行下面的命令，第一列就是 UDID。第一次连接要装设备驱动，按设备准备操作。

1kxdevice device list

装了 iTunes 的也可以在设备摘要页点击「序列号」一栏，切换出 UDID；第三方设备管理工具的设备信息页一般也能直接复制。

在 Devices 页点加号，Platform 选 iOS，填设备名和 UDID，点 Continue 保存。每类设备每个会员年度最多注册 100 台，删掉的设备在本年度内仍然计数，不要随手注册。

生成描述文件

  1. 在 Profiles 页点加号。开发选 iOS App Development；上架选 App Store Connect；发给测试人员直接安装选 Ad Hoc。
  2. 选择上一步的 App ID。
  3. 勾选要允许的证书。Development 描述文件可以同时勾选团队所有人的开发证书，一份文件大家共用。
  4. Development 和 Ad Hoc 类型勾选要安装的设备。App Store Connect 类型没有这一步。
  5. 起一个好认的名字，如 MyApp_Dev，点 Generate，然后 Download 得到 MyApp_Dev.mobileprovision。

描述文件在生成的那一刻就把证书、设备和能力固定下来。之后新增设备、给 App ID 开通新能力、换了证书，都要回到 Profiles 页编辑这份描述文件，保存并重新下载，否则构建或安装会报错，具体报错和处理见iOS 签名报错与 ipa 安装失败的解决办法。

放进 KXBuild 的证书目录

证书目录有两个位置，工程根目录下的 keychain 只对该工程生效，KXBUILD_HOME 下的 keychain 所有工程共用，Windows 上默认是 %USERPROFILE%\kxbuild\keychain。把 .p12 和 .mobileprovision 放进去，并在同目录新建 password.properties，每行写一张证书的「文件名=密码」。

1keychain\
2├─ development.p12
3├─ MyApp_Dev.mobileprovision
4└─ password.properties

1development.p12=你导出时设的密码

文件名要和 .p12 完全一致，区分大小写，密码不加引号。放好之后构建时按工程中的签名设置自动选择证书和描述文件，不需要在 KXBuild 里另外配置，规则见证书与签名。

最后连上手机构建并安装一次，能在手机上打开 App 就说明证书、描述文件和设备都对上了。

1kxbuild build .\MyApp.xcodeproj --install

ios.key、ios.csr、.cer、.pem 这些中间文件不需要放进证书目录。

证书到期、续期和备份

到期前 Apple 会发邮件提醒。开发证书到期后，用它签名的开发版 App 装不上也打不开，重新构建即可；发布证书到期不影响已经在 App Store 上架的版本，但 Ad Hoc 包会失效，也不能再用它上传新构建。

续期 证书不能延长，只能申请一张新的。按本文步骤重新生成 CSR 上传即可，也可以沿用原来的 ios.key 再生成一份 CSR，省去管理新私钥。拿到新证书后合成新的 .p12，再到 Profiles 页编辑所有用到旧证书的描述文件，改选新证书，保存并重新下载，替换证书目录里的旧文件。

备份 把 ios.key 和合成好的 .p12 连同密码存进密码管理器或加密的团队共享盘，不要提交进代码仓库。换电脑、给构建服务器配证书时，直接复制 .p12 和 password.properties 即可，不用重新申请。

私钥丢了 在 Certificates 页吊销这张证书，重新走一遍申请流程。吊销发布证书前先和团队确认没有人正在用它出包。