企业官网建设流程全解析

uni-app 打包出来的 iOS 应用，如果不上架 App Store，怎么让用户真正装到手机上？这个问题我在去年一个企业内部工具项目里被结结实实地卡了三天。项目是个给区域销售团队用的门店巡检 App，用 uni-app 写的，Android 那边一个 apk 甩进群里就完事，iOS 这边却处处是坎：证书类型选错、描述文件没绑设备、plist 的 MIME 类型不对、安装到一半提示无法验证完整性。每一步都像是有人故意藏在暗处等你踩。最后跑通那一刻我才意识到，iOS 的 ipa 内部分发根本不是打包完发个链接这么简单，它是一整条从证书类型判断、设备注册、打包签名、itms-services 分发到故障排查的完整链路，任何一环脱节，用户看到的就只有一句冷冰冰的安装失败提示。这篇就按我当时的真实处理顺序，把 uni-app 打包 iOS ipa 之后做内部分发的整套流程拆开讲清楚，包括每一步为什么这么做、哪些参数不能乱填、以及我踩过的坑到底是怎么冒出来的。

1. 先分清 ipa 内部分发的三条路，选错方向后面全是白干

1.1 Ad Hoc、企业内部分发、TestFlight 的适用边界

刚开始我犯的最大错误，是没想清楚自己属于哪一类分发场景，直接拿了一个企业证书就开始打包。结果打包出来的 ipa，公司内部员工能装，我拿给两个外部合作方的机器测试就装不上，折腾了半天才发现根子上是分发方式选错了。

先把三条路的边界说清楚。Ad Hoc 用的是发布类型证书，设备是白名单制，必须提前把测试设备的 UDID 加到 Apple Developer 后台，一年内每种设备类型最多 100 台。它的优势是安装最稳定、掉签概率最低，缺点是设备名单是硬约束，多一台都装不上。企业内部分发走的是企业开发者账号的 In-House 证书，不需要绑定 UDID，理论上装多少台都行，但它的使用范围苹果有明确限定，只能给本企业员工或组织内部成员使用，不能拿去向公众分发。TestFlight 属于官方测试通道，用 App Store 发布证书上传到 App Store Connect，外部测试员需要经过一次 Beta 审核，好处是安装体验最接近正式版，坏处是审核同样要等，而且每次提交新构建都要重新走流程。

1.2 我的项目最后为什么落在 Ad Hoc + 自建下载页

巡检 App 的使用者一共三十来号人，全部是公司员工，按说企业证书更省事。但当时我们企业开发者账号的申请还没走完，走的是个人开发者账号，于是只能选 Ad Hoc。回过头看，这个被迫的选择反而让我把最硬的那部分基本功练了一遍：设备 UDID 怎么收、描述文件怎么带设备、下载页怎么做。

这里有个需要提前想明白的点：Ad Hoc 的设备名额是按年重置的，也就是每年账号续费之后名额会刷新，但一年之内删掉的设备不会把名额还给你。我第一年就是因为没规划，随手把几台已经离职同事的设备加进去，后来新同事入职时名额就紧张了。所以建议是，收集 UDID 之前先确认名单，宁缺毋滥，离职的设备老老实实等到下一年度再清理，别指望删了就能立刻腾出位置。

提示：企业证书不是万能钥匙。苹果对 In-House 证书的使用范围有明确约束，违规对外分发一旦被检测到，证书会被吊销，届时所有已安装的设备都会直接失去作用。这属于合规红线，别去试探。

1.3 UDID 收集这一步，先解决怎么拿到设备标识

UDID 收集听起来最简单，实际上最容易在这里浪费半天。最稳妥的方式是让用户连电脑，用 Finder 或 iTunes 的设备信息页，点两下序列号区域切换到 UDID，复制出来发给你。这个方式最准，但需要用户有电脑。

另一种方式是做一个描述文件让用户用手机直接装，装完系统会带着 UDID 请求一个回调地址，服务端拿到之后解析。这个方式对用户最友好，但苹果在近几年的系统版本里对这种方式做了收紧，普通开发者账号走这条路会麻烦很多，很多时候需要开发者账号本身就具备设备注册能力，否则用户体验会很割裂。我的做法是把两种方式都写进操作指引里，优先推荐连电脑，实在没有电脑的再走描述文件那条路，同时在群里提前说明 iOS 版本差异可能导致拿不到 UDID，避免用户反复折腾。

拿到 UDID 之后要干的事其实很机械：登录开发者后台，在 Certificates, Identifiers & Profiles 里的 Devices 分类下一台台添加，或者用批量导入。UDID 是一串 40 位的十六进制字符，中间没有分隔符，导入时千万别手抖加了空格或者换行，否则后面生成描述文件时会包含一台无效设备，安装时直接报错。

2. 证书与描述文件：打包前必须一次性理清的对应关系

2.1 证书、App ID、描述文件三者到底谁管什么

这一步是整条链路里概念最容易混淆的地方。我见过太多人把证书和描述文件混为一谈，结果打包时选了 A 证书配 B 描述文件，ipa 生成了但装不上。

用一句大白话概括：证书是证明你是谁，App ID 是证明这个应用叫什么，描述文件是把这两者和设备名单绑在一起的一张授权凭据。

证书分开发证书和发布证书。开发证书用来真机调试，发布证书用来做 Ad Hoc 或上架。它们的区别在于签名时使用的私钥用途不同，Ad Hoc 必须用发布证书，用开发证书签出来的包是装不到别人的设备上的。

App ID 就是 Bundle Identifier，格式通常是反写的域名，比如 com.company.inspection。这个值一旦确定，后面所有环节都必须完全一致，描述文件里的 App ID、uni-app 打包时填的 Bundle ID、plist 里的 bundle-identifier，三者有一个字母对不上就完蛋。

描述文件，也就是 mobileprovision，是把发布证书、App ID、设备 UDID 名单三者绑定后由苹果签发的文件。Ad Hoc 描述文件里会明确列出允许安装的设备，安装时系统会拿当前设备的 UDID 去比对，不在名单里就拒绝安装。

注意：证书的 .p12 文件在导出时一定要设置密码，uni-app 云打包时需要同时提供 .p12 和密码，缺一不可。导出的 .p12 里必须包含私钥，只导出公钥的那种是没用的。

2.2 描述文件生成时的三个真实坑

第一个坑是 App ID 类型选错。在开发者后台创建 App ID 时，如果勾选了额外能力（比如推送、关联域名），描述文件里就会带上对应的 entitlement。而 uni-app 打包时如果没在模块配置里勾选对应功能，签名后的包和描述文件里的权限就会不一致，安装后可能立马闪退。我的建议是，按最小必要原则创建 App ID，用不到的能力一律不勾。

第二个坑是描述文件的有效期。UDID 描述文件通常有效期一年，和开发者账号续费周期一致。但如果你是在年度中途生成的，它的到期时间不会跟着往后顺延，还是卡在账号年费到期那天。我那次就吃了这个亏，八月份生成的描述文件，次年二月底失效，用户在春节前一周集中反馈打不开，非常被动。解决办法是在描述文件生成后立刻把过期日期记进日历，提前一个月准备续签和重新分发。

第三个坑是证书吊销后的连带影响。如果团队里有人误操作把发布证书吊销了，那么所有用这张证书生成的描述文件会同时失效。这时候你只能在后台重新生成证书和描述文件，然后用新证书重新打一次包，之前发出去的 ipa 全部作废。所以证书的 .p12 和密码一定要在团队内部有备份，最好是放在受控的密码管理工具里，不要只存在某一个人的电脑上。

2.3 描述文件自检：用命令提前验证，别等用户来告诉你

ipa 打包出来之后，可以直接用命令行验证描述文件里的信息，这一步能省掉大量来回沟通。把 ipa 解压，找到 Payload 目录下的 .app，里面有个 embedded.mobileprovision，它是一个 CMS 签名的 plist，用下面这条命令可以解出来：

unzip -o inspection.ipa -d ./unpacked cd ./unpacked/Payload/Inspection.app security cms -D -i embedded.mobileprovision > profile.plist plutil -p profile.plist | grep -A 5 -E "Name|ExpirationDate|ProvisionedDevices"

解出来的内容里，ProvisionedDevices 就是设备白名单，ExpirationDate 是到期时间，Name 是描述文件名称。每次发版之前我都跑一遍，确认设备确实在里面、到期时间还够用，再往群里发链接。这个习惯帮我拦下过至少两次低级失误。

再顺手验证一下签名信息：

codesign -dvvv --entitlements :- Payload/Inspection.app

输出的内容里能看到签名用的证书主体和 application-identifier，确认它和你在开发者后台看到的一致，就说明打包环节没问题。

3. uni-app 打包 ipa 那条链：参数填错一次，重打十分钟

3.1 HBuilderX 云打包里几个容易搞混的字段

uni-app 的 iOS 打包在 HBuilderX 里走发行菜单下的原生 App 云打包，界面看着不复杂，但几个字段特别容易填错。

第一个是 AppID 和 Bundle ID 的区别。HBuilderX 里看到的 AppID 是 DCloud 侧的标识，形如 __UNI__XXXXXXX，它和苹果的 Bundle Identifier 完全是两回事。云打包时需要在 iOS 配置里单独填写 Bundle ID，这个值必须和开发者后台的 App ID 完全一致，包括大小写。我第一次打包就是在这个地方少填了一个段，云打包成功，安装却一直失败，排查了很久。

第二个是证书类型的选择。云打包界面会让你上传 .p12 证书和 .mobileprovision 描述文件，选择打包方式时要区分正式包和自定义调试基座。给用户下载的必须是正式包，调试基座只能在开发阶段用，且依赖 HBuilderX 的连接，用户拿到手是装不上也用不了的。

第三个是模块配置。uni-app 把很多原生能力做成了模块，比如推送、支付、蓝牙、地图。这里有一个隐含的坑：模块一旦勾选，打包时会往工程里注入对应的 framework 和 entitlement，这时候你的描述文件必须同步包含对应的权限，否则签名校验会失败。我那次给巡检 App 加了定位和蓝牙模块，描述文件里忘了带上对应的 App ID 能力，结果安装后一进到扫码页面就闪退。

云打包的时间通常在五到十五分钟不等，取决于队列。建议在正式分发前先打一个自测包，装到自己和一台备用机上确认没问题，再打正式包分发给所有人，避免同一套参数重打两遍。

3.2 打包完成后的 ipa 该怎么核验

云打包结束后会给出一个下载链接，拿到 ipa 别急着发出去，先做几件事。

第一，确认包体大小和上一次相比没有剧烈变化。如果比上一个小了很多，有可能是资源没打进去，比如静态资源路径配错、manifest 里的分包配置有问题。uni-app 打包后布局异常这类问题，很多时候就是资源没同步导致的。

第二，在真机上安装一次，走一遍核心流程。我一般会重点测三类操作：启动到首页、需要原生权限的功能（相机、定位、蓝牙）、以及网络请求。这三类覆盖了绝大多数签名和权限相关的问题。

第三，用前面说的命令解析一次 embedded.mobileprovision，确认设备名单和到期时间。

第四，如果是远程升级场景，还要确认 uni-app 的版本号配置有没有更新。uni-app 的 wgt 资源升级依赖版本号比对，如果只改了 ipa 没动版本号，用户端可能不会触发升级提示，这个坑在同时维护 ipa 和 wgt 两条线的时候特别容易踩。

3.3 什么时候必须放弃云打包转离线打包

云打包省事，但有几种情况必须转成离线打包。

一是需要集成官方模块市场里没有的原生 SDK。云打包只支持 HBuilderX 内置和官方插件市场上的模块，如果你要接一个第三方的原生库，就必须走离线打包，在 Xcode 工程里手动配置。

二是需要定制原生工程的配置，比如修改 Info.plist 里的 URL Scheme、配置后台模式、调整编译参数。这些在云打包里能改的范围有限。

三是需要做代码混淆加固。加固之后 ipa 的签名会变化，必须重新用证书签名，然后用解析命令确认签名后的 entitlements 没有被破坏，再走分发。加固后重新签名这个环节，重点在于签名时要用对证书和描述文件，且要确认加固工具没有把 embedded.mobileprovision 一起改坏。

离线打包的代价是环境维护成本高，Xcode 版本、SDK 版本、依赖库版本都要自己盯。我的判断标准是：能云打包就云打包，只有被功能逼到墙角时才转离线，并且转过去之后要做好版本锁定记录，避免下次换电脑打包时环境不一致。

4. 把 ipa 变成点一下就装的下载页

4.1 itms-services 协议到底在干什么

ipa 打包出来之后，直接给用户发文件是装不上的，iOS 系统不允许用户从聊天软件里直接安装一个 ipa。必须通过 itms-services 这个协议来触发安装。它的完整形式是这样一条链接：

itms-services://?action=download-manifest&url=https://example.com/app/manifest.plist

用户在 Safari 里点开这条链接，系统会去请求 url 参数指向的那个 plist 文件，从里面读到 ipa 的下载地址、应用名称、图标地址等元信息，然后弹出安装确认框。整个过程的关键在于：这条链接必须由 Safari 打开，从微信里直接点通常是被拦截的，所以要引导用户复制到 Safari 或者用系统浏览器打开。

这也是为什么很多下载页会做 UA 判断。检测到是 iOS 设备，就展示安装按钮并提示用 Safari 打开；检测到是 Android，就跳到 apk 下载；检测到是电脑，就显示二维码。这套判断逻辑不复杂，但能显著降低用户的操作门槛。

4.2 manifest.plist 的字段逐个说清楚

plist 文件是整个分发环节的核心，字段写错一个，安装就失败。一个可用的最小版本长这样：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>items</key> <array> <dict> <key>assets</key> <array> <dict> <key>kind</key> <string>software-package</string> <key>url</key> <string>https://example.com/app/inspection-1.2.0.ipa</string> </dict> <dict> <key>kind</key> <string>display-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://example.com/app/icon-57.png</string> </dict> <dict> <key>kind</key> <string>full-size-image</string> <key>needs-shine</key> <true/> <key>url</key> <string>https://example.com/app/icon-512.png</string> </dict> </array> <key>metadata</key> <dict> <key>bundle-identifier</key> <string>com.company.inspection</string> <key>bundle-version</key> <string>1.2.0</string> <key>kind</key> <string>software</string> <key>title</key> <string>门店巡检</string> </dict> </dict> </array> </dict> </plist>

几个字段值得单独说。software-package 的 url 必须是 ipa 的直接下载地址，不能是跳转页。display-image 对应安装过程中显示的图标，尺寸建议 57×57；full-size-image 对应 512×512，安装完成后桌面图标会用它。metadata 里的 bundle-identifier 必须和 ipa 里实际的 Bundle ID 一字不差，bundle-version 是展示用的版本号，title 是安装弹窗里显示的应用名。

我踩过的坑是 bundle-version 随手写了带中文的版本描述，结果安装时解析异常。这个字段建议就用纯数字加点的格式。

4.3 两个隐形门槛：HTTPS 和 MIME 类型

这是最容易被忽略、也最让人抓狂的两个点。

第一，从较新的 iOS 版本开始，itms-services 要求 plist 和 ipa 都必须通过 HTTPS 提供，HTTP 链接会被直接拒绝，连报错都不给。所以你的分发服务器必须有可用的证书。证书得是受信任的机构签发的，自签名证书在大多数设备上会被拦。我的做法是给分发域名配一张正式的证书，用自动续期的方式维护，避免到期后下载页集体失效。

第二，MIME 类型。plist 文件如果服务器返回的是 application/octet-stream，系统可能不认；ipa 如果返回的是 text/plain 之类的类型，也会出问题。Nginx 下的配置大概是这样的：

location ~* \.plist$ { default_type application/x-plist; add_header Content-Disposition inline; } location ~* \.ipa$ { default_type application/octet-stream; add_header Content-Disposition attachment; }

配完之后用 curl 确认一下响应头：

curl -I https://example.com/app/manifest.plist

看到 Content-Type 是 application/x-plist 才算对。这一步做完，安装成功率会有明显提升。

4.4 下载页的引导文案比技术本身更重要

技术上跑通之后，真正影响体验的是引导。用户不懂什么是 UDID，也不知道为什么要点 Safari 打开。我在下载页上做了几件事：识别到微信内置浏览器时，直接显示一个遮罩，提示点击右上角用浏览器打开；识别到 iOS 且版本过低时，提示系统版本不满足；安装按钮下方放一行小字，说明首次打开需要去设置里信任证书。

还有一个细节，安装过程中图标是灰色的，很多用户会以为装坏了。我在页面上加了一句说明，告诉他们图标变亮就代表装好了。这句话看起来微不足道，但确实减少了很多重复提问。

5. 装机失败的完整排查链路

5.1 无法安装此 App 时按什么顺序查

这句提示是内部分发里出现频率最高的错误，但它的成因有很多种。我总结的排查顺序是这样的。

第一步，确认描述文件里的设备名单。把 embedded.mobileprovision 解出来，看当前设备的 UDID 是否在里面。这是最常见的原因，尤其是新入职同事的设备还没加进去。

第二步，确认描述文件是否过期。同一个命令能看到 ExpirationDate，如果已经过期，只能重新生成描述文件并重新打包。

第三步，确认 bundle-identifier 是否一致。plist 里写的、ipa 里实际的、下载页配置的，三处必须完全一致。

第四步，确认 plist 和 ipa 的 URL 都能正常访问，且是 HTTPS。用手机自带浏览器直接打开这两个地址，能下下来才算通。

第五步，确认 MIME 类型。这一步前面已经说过，用 curl 查响应头。

按这个顺序走，绝大多数问题都能定位到具体某一环。最怕的是上来就乱改，改了一堆参数反而把原本正常的部分搞坏了。

5.2 未受信任的开发者提示怎么处理

Ad Hoc 分发的包通常不会触发这个提示，因为它是通过描述文件授权安装的。企业证书分发的包在首次打开时会提示无法验证开发者，需要用户去设置里的通用-描述文件与设备管理，找到对应的企业级应用描述文件，手动点击信任。

这个操作必须由用户自己在设备上完成，开发者没有办法绕过。所以如果你的分发对象里有对手机操作不熟悉的人，最好把截图步骤做成一份图文指引，一步步标出来。我当时的做法是录了一段二十秒的屏幕录制，发到群里，安装成功率一下子从六成上到了九成以上。

需要注意的是，如果设备上已经信任过同一个企业主体的旧描述文件，换新证书之后可能需要重新信任一次。这个和描述文件的签名主体是否变化有关，换证书时最好在通知里提醒一句。

5.3 装完能打开，但一进某个页面就闪退

这类问题基本和分发链路无关，属于打包配置问题。我遇到过的几类原因。

一是权限声明缺失。比如相机、相册、定位、蓝牙，如果 Info.plist 里没有对应的用途描述，系统在调用时不会弹权限框，直接让进程挂掉。uni-app 云打包时会根据你勾选的模块自动注入一部分，但不是全覆盖，涉及蓝牙、定位这类敏感能力时，最好在离线打包工程里手动检查一遍。

二是模块和描述文件 entitlement 不匹配。前面说过，勾了推送却没有对应的 App ID 能力，启动阶段就可能崩。

三是加固或重签名破坏了 entitlements。加固后的包如果重新签名时没带上原来的权限，表现就是各种奇怪的闪退。验证方法还是用 codesign 那条命令，把签名后的 entitlements 和签名前的对比一下。

四是 JavaScript 层的异常引发的白屏，看起来像闪退。这种情况在 uni-app 里更常见于某个页面用了设备模拟器不支持的 API，或者在真机上 new Date() 的格式化字符串不兼容。这类问题建议在打包前用真机自定义基座先跑一遍，别等分发之后才暴露。

5.4 掉签和续签该怎么应对

掉签是所有内部分发方案都绕不开的问题。表现为某一天用户突然反馈应用打不开了，或者提示无法验证。根因通常是证书被吊销或描述文件过期。

应对的核心是提前做，而不是等出事再做。我的做法是维护一张表，记录证书序列号、描述文件名称、生成日期、到期日期、绑定的 Bundle ID。每个月看一次，到期前三十天启动续签流程。续签的步骤是：重新生成描述文件，用同一张证书重新打包，更新 plist 里的 bundle-version，把新的 ipa 传到服务器。

这里有个可以省事的技巧：下载页的 plist 地址保持不变，只改 plist 内容里的 ipa 地址和版本号。这样用户不需要重新获取新的链接，直接点原来的入口就能更新。我在项目里把这个入口做成了一个固定短链，后续所有版本迭代都只是替换服务端的文件，用户侧的体验非常顺。

6. 让这套流程变得可复用，而不只是救一次火

6.1 版本号、plist 与下载页的联动

一次性的分发谁都能做，难的是每次发版都不出错。我后来把下载页做成了一个带版本参数的页面，比如 /download?v=1.2.0，服务端根据版本号动态生成对应的 plist 内容，同时把 ipa 文件按版本号命名存放在对象存储里。

这样做的好处有三个。一是回滚变得极其简单，只需要把下载页的默认版本指回上一个版本即可。二是历史版本天然留档，用户报问题时能确认他装的是哪一版。三是配合埋点，可以看到每个版本的下载次数和安装转化情况，虽然不精确，但足够判断哪个版本分发失败了。

uni-app 侧的版本号也要同步维护。manifest.json 里的 versionName 和 versionCode 是两个不同的字段，前者是给人看的，后者是给系统判断升级用的。如果只在页面上改了展示版本，没改 versionCode，通过 wgt 走资源升级的用户端不会触发更新。这个坑我在同时维护 ipa 和 wgt 两条分发线时踩过，后来干脆把两个值做成同一份配置读出来，避免手改漏改。

6.2 设备变更的增量处理

团队人员流动是常态，设备名单的维护不能等到年底一起做。我的做法是在下载页上加了一个简单的申请入口，新人填自己的 UDID 和设备型号，提交之后通知管理员去开发者后台添加，添加完成后重新生成描述文件并重打包。

这里要接受一个现实：Ad Hoc 模式下，每加一台设备都要重新生成描述文件、重新打一次包。听起来很麻烦，但实际频率并不高，一个月一两次。为了避免频繁重打，我会在有一定批次时统一处理，比如攒三到五台设备一起加。代价是新人要等一两天，所以入职流程里要提前说明。

另外，描述文件重新生成后，旧包并不会立刻失效，它还是按原来的描述文件在跑。真正让旧包失效的是描述文件本身过期或者证书被吊销。所以设备增量的处理不影响已经在用的用户，可以放心操作。

6.3 我在这套流程上踩过的三个运维坑

第一个坑是服务器磁盘写满导致 ipa 下载中断。ipa 文件动辄几十兆到上百兆，几个版本堆在一起很容易把盘占满。后来我改成用对象存储托管 ipa，服务器只负责生成 plist 和做重定向，这个问题就彻底消失了。

第二个坑是 CDN 缓存了旧的 plist。更新 plist 内容之后，部分用户拿到的还是缓存版本，安装的还是老 ipa。解决办法是给 plist 加不缓存的响应头，或者在文件名里带上版本号，让 URL 本身变化。我最后选的是后者，虽然要改下载页里拼接的逻辑，但比其他方案都省心。

第三个坑是内网和外网地址混用。有一次打包时把 ipa 地址配成了内网地址，公司内部测试全都正常，一发给外部测试就全军覆没。这个错误的隐蔽性在于内部测试的网络环境天然能访问内网，压根发现不了。从那以后我形成习惯，分发前用手机蜂窝网络单独验证一遍所有链接，不连公司 WiFi。

提示：分发地址尽量不要用临时 IP 或者带端口的地址，一是证书配置麻烦，二是换环境时容易漏改。老老实实用域名，一次配好长期受益。

这套流程跑顺之后，我们后来做新项目的内部分发基本就是照着抄：确定分发方式、收集设备、生成描述文件和证书、云打包、核验 ipa、配 plist 和下载页、验证链接、发通知。整个过程半天之内能完成，剩下的时间基本都花在给新人解释为什么要用 Safari 打开上。我个人在实际操作中的体会是，iOS 内部分发这件事，真正难的不是技术本身，而是所有环节都不能有一点想当然。证书类型、设备名单、URL 协议、MIME 类型、缓存策略，每一项都是那种平时不出问题、一出问题就完全没法用的类型。把检查清单写成文档，每次发版照着过一遍，比事后救火要轻松太多。