# RN 构建 iOS 包发布到 AppStore 全流程 证书描述文件与上架实战

> 一份 React Native 项目打 iOS 包的完整流程记录。从 Apple Developer 后台创建 App ID、Xcode 自动生成开发与发布证书、配置 Development 和 Distribution 描述文件，到 Archive 导出 ipa 发蒲公英内测、注册设备 UDID，再到 App Sto

- 原文：https://feinterview.poetries.top/blog/ios-build
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2023-10-22
- 可见范围：免费部分

---

第一次给 `React Native` 项目打 iOS 包上架，最劝退的不是代码，是苹果那一整套签名体系。你会在 `Apple Developer` 后台、`Xcode`、`App Store Connect` 三个地方来回跳，面对 `Identifiers`、`Certificates`、`Profiles`、`Devices` 这四个长得都差不多的菜单，不知道该先点哪个。等你终于点完了，`Xcode` 一句 `No profiles for 'com.xxx.app' were found` 又把你打回原点。

这篇是我把这条路完整走通一遍之后留下的记录，从后台建 `App ID` 开始，一直到包被 `App Store Connect` 收下、审核被拒之后怎么补救为止。每一步配了截图，也把每一步「在做什么」和「做完应该看到什么」写清楚。

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

- 证书、App ID、描述文件、设备这四样东西各自管什么，它们是怎么串起来的
- 为什么推荐让 `Xcode` 自动管理签名，而不是在后台手动创建证书
- 开发环境（`Development`）和正式环境（`Distribution`）两套证书 + 描述文件怎么配
- `Xcode` 里 `Signing & Capabilities` 那一屏每个选项该怎么填
- 怎么 `Archive` 导出 `ipa`，上传到蒲公英给测试同学装
- 设备 `UDID` 从哪来、注册到哪、注册完为什么还得重新打包
- `App Store Connect` 建应用、传构建版本的完整路径
- 审核被拒最常见的那个原因，以及重新构建时版本号怎么改

## 一、先把四个概念理顺

苹果这套签名体系之所以绕，是因为它把一件事拆成了四样东西，缺一不可。动手之前先花两分钟理清楚，后面所有操作就都有的放矢了。

**App ID（Identifiers）** 是你这个 App 的唯一身份，对应 `Xcode` 里的 `Bundle Identifier`，形如 `com.company.appname`。它还负责声明这个 App 要用哪些能力（推送、`Sign in with Apple`、`App Groups` 这些）。一个 App ID 一旦创建就不能改，所以命名前想清楚。

**证书（Certificates）** 证明「这个包是我签的」。它分两大类：`Apple Development`（开发证书，装到调试设备上跑）和 `Apple Distribution`（发布证书，用来打 `Ad Hoc` 内测包和上架包）。证书本身和具体哪个 App 无关，一个团队的证书可以给所有 App 用。

**描述文件（Provisioning Profiles）** 是把上面几样绑在一起的那张「许可证」。它记录了「哪个 App ID + 哪张证书 + 哪些设备」这三者的组合，装到设备上的包必须能匹配上一份有效的描述文件，系统才肯让它运行。

**设备（Devices）** 就是通过 `UDID` 注册进后台的测试机列表。只有 `Development` 和 `Ad Hoc` 两种描述文件需要它，上架用的 `App Store` 描述文件不含设备列表，因为它面向所有人。

先说结论，这四样里最容易出问题的是描述文件，因为它是唯一一个「组合体」，上游任何一项变了（换了证书、加了设备、改了 Bundle ID），它就得重新生成，而且**重新生成之后必须重新打包**，旧包不会自动生效。

> 使用`xcode`来管理自动生成证书，不需要在管理后台创建

这句是整篇的一个关键取舍。证书理论上可以在后台手动走「生成 CSR 请求文件 → 上传 → 下载 cer → 双击导入钥匙串」这一套，但那套流程步骤多、还容易把私钥搞丢。`Xcode` 的 `Automatically manage signing` 会替你把证书和描述文件都建好并保持同步，绝大多数情况下够用了，下面就按这个思路走。

## 二、在 Apple Developer 后台创建 App ID

第一步是给 App 上户口。

> 登录 https://developer.apple.com/account

登录之后进入 `Certificates, Identifiers & Profiles` 这个板块，这是后面所有后台操作的总入口。

![登录 Apple Developer 账号后进入 Certificates, Identifiers & Profiles 总入口](https://s.poetries.top/uploads/2023/10/d3d19228ec48dfe2.png)

进来先确认左上角的团队名对不对。如果你同时在多个开发者账号里（比如个人账号和公司账号），这里选错了，后面证书和描述文件全建到另一个团队去了，`Xcode` 里怎么都匹配不上。

在左侧菜单点 `Identifiers`，然后点列表左上角那个蓝色的加号新建。

![在左侧菜单中选择 Identifiers 并点击加号新建标识符](https://s.poetries.top/uploads/2023/10/19657900fcb37bef.png)

点完加号会先让你选类型，选第一项 `App IDs` 然后继续。这一屏还有 `Services IDs`、`Pass Type IDs` 之类的选项，那些是给推送服务、`Wallet` 卡券用的，跟打包上架没关系，别点错。

![在新建标识符的类型选择页选择 App IDs 类型](https://s.poetries.top/uploads/2023/10/9348e21eb02eae74.png)

选完类型下一屏会再问一次是 `App` 还是 `App Clip`，选 `App`。这两屏是苹果在某次改版后拆出来的，不同时期进来看到的步数可能不一样，认准最后填 `Bundle ID` 那一屏就行。

![继续选择 App 类型进入 App ID 的信息填写页](https://s.poetries.top/uploads/2023/10/4c8cddc046e42324.png)

到了填信息这一屏，两个关键字段。`Description` 随便写个能认出来的名字；`Bundle ID` 选 `Explicit`（显式），填你项目里的那个包名，比如 `com.poetries.myapp`。

![填写 App ID 的 Description 与 Explicit Bundle ID](https://s.poetries.top/uploads/2023/10/68e759bd80a6b7d0.png)

这里有个坑要注意，`Bundle ID` 必须和 `Xcode` 项目里 `General → Identity → Bundle Identifier` 那一栏**一字不差**，大小写也算。RN 项目里这个值在 `ios/项目名.xcodeproj` 的 `PRODUCT_BUNDLE_IDENTIFIER` 里，改的时候记得 `Debug` 和 `Release` 两个配置都要改。另外别选 `Wildcard`（通配符），通配符 App ID 不支持推送等大部分 `Capabilities`，后面想加功能就得推倒重来。

往下滚是 `Capabilities` 列表，用不到的能力先都别勾，之后需要了随时回来加。确认无误点 `Continue`，再点 `Register` 完成。

![确认 App ID 信息后完成注册，列表中出现新建的标识符](https://s.poetries.top/uploads/2023/10/1c453d7171b4d71f.png)

回到 `Identifiers` 列表能看到刚建好的这一条，App ID 这一步就完事了。

## 三、让 Xcode 自动生成开发证书

App ID 有了，接下来是证书。这一步不用回后台点，交给 `Xcode` 更省事。

先在 `Xcode` 顶部菜单 `Xcode → Settings → Accounts`（旧版本叫 `Preferences`）里，把你的 Apple ID 加进去并选中对应的 Team。账号没加进来，后面自动签名一定失败。

![在 Xcode 的 Accounts 设置中添加 Apple ID 并选中开发者 Team](https://s.poetries.top/uploads/2023/10/864c4d1828d36193.png)

加完账号，回到项目，选中 `TARGETS` 下的主 target，切到 `Signing & Capabilities` 标签页，勾上 `Automatically manage signing`，`Team` 选你的团队。

![在 Signing & Capabilities 中勾选 Automatically manage signing 并选择 Team](https://s.poetries.top/uploads/2023/10/7ff0853d6763d1e7.png)

勾上的一瞬间 `Xcode` 就开始干活了：它会去后台查有没有可用的开发证书，没有就自动申请一张，同时生成一份匹配当前 Bundle ID 的 `Development` 描述文件并下载到本地。整个过程几秒钟，成功之后这一屏的 `Signing Certificate` 会显示成 `Apple Development: 你的名字 (XXXXXXXXXX)`，下面的红色报错消失。

> 然后到后面就看到自动创建的证书了

![回到 Apple Developer 后台的 Certificates 列表，可以看到 Xcode 自动创建的开发证书](https://s.poetries.top/uploads/2023/10/dae17eae4f107800.png)

回后台的 `Certificates` 菜单刷新一下，能看到多了一条 `Apple Development` 类型的证书，创建者就是你。看到它说明自动签名链路是通的。

这里补一句经验，开发证书在账号里是有数量上限的（个人账号更紧），团队人一多很容易顶格。真到了上限，先去后台把那些已经离职同事或者早就换机器的旧证书 `Revoke` 掉再重来，别一直点重试。

## 四、创建 Development 描述文件

自动签名其实已经帮你生成了一份开发描述文件，但很多团队还是习惯在后台显式建一份来管控设备范围，流程也就顺手过一遍，出问题时你才知道去哪看。

在左侧菜单点 `Profiles`，然后点加号新建。

![在左侧菜单选择 Profiles 并点击加号新建描述文件](https://s.poetries.top/uploads/2023/10/43fdac62f1c4ebea.png)

第一屏选类型，在 `Development` 分组下选 `iOS App Development`。注意别选到下面 `Distribution` 分组里去了，那是第六节的事。

![在描述文件类型选择页的 Development 分组下选择 iOS App Development](https://s.poetries.top/uploads/2023/10/08dbd8f12c57cd87.png)

下一屏选 App ID，从下拉里挑第二节建的那个。这里只会列出当前团队下的 App ID，找不到就回去确认团队选对没有。

![为描述文件选择对应的 App ID](https://s.poetries.top/uploads/2023/10/05aab8ad8141cbab.png)

再下一屏选证书，把第三节里 `Xcode` 自动生成的那张 `Apple Development` 证书勾上。可以多选，勾了哪几张，用这些证书签出来的包就都能被这份描述文件覆盖。团队协作时建议全勾，省得每个人各自建一份。

![为描述文件勾选可用的开发证书](https://s.poetries.top/uploads/2023/10/543f027a5d7c2043.png)

接着是选设备。这一屏列出的是后台 `Devices` 里已注册的所有测试机，勾上需要装这个开发包的设备。**没勾进来的设备，包装上去会直接闪退或者根本装不上**，这就是第九节要专门讲注册 UDID 的原因。

![为描述文件勾选允许安装的测试设备](https://s.poetries.top/uploads/2023/10/6232eacf27532221.png)

最后一屏给描述文件起个名字，建议带上环境标识，比如 `MyApp_Dev`，以后在 `Xcode` 下拉里一眼就能认出来。点 `Generate` 生成，然后 `Download` 下载，双击下载好的 `.mobileprovision` 文件，`Xcode` 会自动把它导入。

![填写描述文件名称并生成，随后下载 mobileprovision 文件](https://s.poetries.top/uploads/2023/10/31b7f6ff29a2d551.png)

到这里开发环境这一套（App ID + 开发证书 + 开发描述文件 + 设备）就齐了，用数据线连上一台已注册的设备，`Xcode` 里选中它直接 `Run`，App 应该能装上去跑起来。

## 五、生成 Distribution 正式环境证书

开发那套只能在注册过的设备上跑，要打内测包和上架包，得换一套 `Distribution` 的证书和描述文件。

发布证书同样可以让 `Xcode` 自动生成（`Archive` 的时候它会问你），也可以在后台 `Certificates` 里点加号手动建。手动建的话在类型列表里选 `Apple Distribution`（有些账号下显示为 `iOS Distribution (App Store and Ad Hoc)`），然后按提示上传一份 `CSR` 文件。

![在 Certificates 中新建 Apple Distribution 类型的发布证书](https://s.poetries.top/uploads/2023/10/25717985c486ad13.png)

`CSR` 文件的生成方式是打开 `Mac` 上的「钥匙串访问」，菜单走 `钥匙串访问 → 证书助理 → 从证书颁发机构请求证书`，邮箱填你的，选「存储到磁盘」，得到一个 `.certSigningRequest` 文件，传上去就行。

这里有个团队协作的坑，**发布证书全团队只需要一张**。谁生成的，私钥就在谁的钥匙串里，别人要打包必须从这台机器导出一份 `.p12`（导出时会让你设密码）再导入自己的钥匙串。如果每个人各建一张，很快就会撞上苹果对发布证书数量的限制。

生成完成后下载 `.cer` 双击导入钥匙串，在「我的证书」里能展开看到证书下面挂着一把私钥，才算真的可用；只有证书没有私钥的话，`Xcode` 打包时会提示找不到匹配的签名身份。

## 六、创建 Distribution 描述文件

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/blog/ios-build
