uni-app 全平台打包上线一站式指南

一、uni-app 打包上线基础介绍

uni-app 作为一款跨平台开发框架，具有众多显著的特点和优势。

特点：

• 兼容性出色，一套代码能够编译运行于多个平台，如 iOS、Android、H5 等，极大地节省了开发成本。

• 开发速度快，HBuilderX 的支持使得开发和编译效率颇高。

优势：

• 学习成本低，基于 Vue.js 开发，对于熟悉 Vue 语法和微信小程序开发的人员来说，能够快速上手。

• 扩展能力强，支持 nvue 以及原生的 iOS 和安卓开发，便于功能拓展。

为何选择 uni-app 开发：

• 跨平台支持，减少了为不同平台单独开发的繁琐，一套代码多端通用。

• 功能丰富，提供了路由、HTTP 请求、状态管理等多种功能和组件，满足复杂应用开发需求。

• 社区活跃，开发者能够获取丰富的文档、教程和示例代码等资源，方便交流与学习。

全平台打包上线的重要性：

全平台打包上线意味着能够覆盖更广泛的用户群体，提升应用的影响力和市场占有率。对于开发者而言，不仅能够减少重复开发工作，还能实现快速迭代和更新，及时响应市场需求。同时，统一的打包上线流程有助于保证各平台应用的一致性和稳定性，提升用户体验。

二、iOS 打包上线详细教程

（一）准备工作

首先，确保已安装好必要的软件，如 Xcode、HBuilderX 等。同时，配置好项目的相关信息，包括 AppID、Bundle Identifier 等。另外，还需准备好苹果开发者账号，并在账号中进行一些基础设置。

（二）开发者账号开通

开通苹果开发者账号的流程如下：

1. 访问苹果开发者官网，使用个人或公司信息进行注册。

1. 根据提示选择开发者类型，如个人开发者或公司开发者，并支付相应的费用。

1. 注册完成后，可能需要等待 1 - 3 个工作日，账号才能正式用于 APP 上传功能。

注意事项：

• 注册时需提供准确的信息，避免审核不通过。

• 选择合适的开发者类型，根据实际需求决定。

（三）证书与文件申请

1. 生成证书请求文件：在 Mac 电脑上通过“钥匙串访问”工具生成证书请求 (.certSigningRequest)文件。

1. 申请开发证书：在苹果开发者官网，选择对应的证书类型（如 iOS App Development），上传证书请求文件，生成并下载证书。

1. 申请发布证书：类似开发证书的申请流程，选择 iOS Distribution 类型。

1. 申请 App ID：在开发者官网创建 App ID，注意命名规范和功能选项的选择。

1. 申请描述文件：根据开发或发布的需求，选择相应的类型进行申请，并与证书和 App ID 关联。

（四）打包参数配置

在 HBuilderX 中进行如下配置：

1. 打开项目，找到“manifest.json”文件。

1. 选择“编译模式”为“生产模式”。

1. 点击“发行”-“原生 App-本地打包配置”，设置 Xcode 路径、开发者证书、描述文件等参数。

（五）执行打包与上传

1. 在 HBuilderX 中选择“发行”-“原生 App-发行到 iOS 平台”，等待打包完成。

1. 打包成功后，下载保存.ipa 文件。

1. 打开 App Store Connect 管理页面，或者使用相关工具（如 Transporter）上传.ipa 文件。

（六）审核与发布

1. 填写应用的相关信息，如预览图、描述、关键词等。

1. 提交审核，等待苹果官方的审核结果。

1. 若审核通过，应用将在 App Store 上线；若不通过，根据反馈意见进行修改后重新提交。

审核要点：

• 确保应用功能完整，无明显漏洞。

• 遵循苹果的设计规范和政策要求。

三、安卓打包上线详细教程

（一）准备工作

为了顺利进行 uni-app 安卓打包上线，您需要准备以下环境和工具：

• 安装 Java 开发环境（JDK），确保版本为 1.8 及以上。

• 下载并安装 HBuilderX 开发工具。

• 配置好 Android SDK 环境。

同时，还需要进行项目相关的准备工作：

• 确定项目的应用名称、图标等基本信息。

• 梳理项目的功能和权限需求。

（二）证书生成与配置

以下是生成 uni-app 安卓证书的步骤：

1. 打开 HBuilderX，点击帮助，点击开发者云端控制台。

1. 登入后点击应用管理 > 我的应用 > 在应用列表中找到要生成证书的应用（此应用必须是当前账号下的应用）。

1. 进入后点击 Android 云端证书，点击创建证书即可。

生成证书后，需要进行相应的配置，例如填写证书的别名、密码等信息。

（三）打包参数设置

1. 在 HBuilderX 中打开项目，找到“manifest.json”文件。

1. 配置应用的权限，根据实际需求勾选相应的权限选项，如网络访问、存储权限等。

1. 选择打包方式，如传统打包、快速安心打包等，并根据提示设置相关参数。

（四）发布与安装

1. 选择 HBuilderX 中的“发行”-“原生 App-云打包”。

1. 输入安卓包名，一般以域名命名，反过来写。

1. 选择证书类型，如自有证书、公共证书或云端证书。

1. 勾选打正式打包。

1. 等待打包完成，控制台会输出生成的安装包所在文件夹的位置。

1. 进入文件夹，找到生成的 APK 文件，右键选择安装到安卓设备。

在发布与安装过程中，可能会遇到一些问题，如安装失败、权限不足等，需要根据具体情况进行排查和解决。

四、小程序打包上线详细教程

（一）准备与配置

在进行 uni-app 小程序打包上线之前，您需要做好以下准备工作和进行相关配置：

• 注册微信小程序账号，并完成个人信息配置。

• 准备好 uni-app 工程文件，并打开 HBuilderX 开发工具。

• 配置好域名，确保小程序能正常使用网络功能。域名必须是 HTTPS 协议，服务器 TLS1.2 及以上。

• 在 manifest.json 文件中进行相关配置，如设置 AppID 等。

• 检查项目中的分包情况，微信小程序每个分包的大小不能超过 2M，总体积不能超过 20M。

• 处理好图片等静态资源，避免超过 200kb，可将其上传至 CDN 。

• 开启组件按需注入，在 manifest.json->源码视图->mp-weixin 中添加配置"lazyCodeLoading":"requiredComponents" 。

（二）打包流程

以下是 uni-app 小程序的打包步骤：

1. 打开 uni-app 项目，找到“manifest.json”文件。

1. 确认微信小程序的相关配置信息准确无误，包括 AppID 、分包设置等。

1. 点击 HBuilderX 中的“发行”选项，选择“小程序-微信”。

1. 等待打包过程完成，期间可能会出现提示，根据提示进行相应操作。

（三）上传与审核

上传和审核的操作如下：

1. 打包完成后，HBuilderX 会自动调开微信开发者工具（若未安装需先安装）。

1. 在微信开发者工具中，选中右上角的上传按钮，上传小程序代码。

1. 上传成功后，登录微信公众平台，选择版本管理。

1. 找到刚刚上传的版本，点击提交审核。

1. 初次提交审核，需按照要求填写表单，包括版本备注、图片预览等信息。

1. 提交后等待微信官方审核，审核时间一般为 1 - 7 天。

1. 若审核通过，会收到通知，此时可点击发布按钮，将小程序正式上线。

1. 发布时，可选择灰度发布或全量发布。灰度发布可先让部分用户使用，全量发布则所有用户均可看到。

注意事项：

• 上传前确保代码质量，避免因明显错误导致审核不通过。

• 审核过程中保持关注审核状态，及时处理可能出现的问题。

五、常见问题与解决方法

（一）iOS 平台常见问题与解决方法

1. 安全区底部白边问题

• • 问题描述：iPhone 底部自带安全区，可能出现底部白边。

• • 解决办法：在 manifest.json 源码视图的 "app-plus" 中配置 "safearea" : {"bottom" : {"offset" : "none"}} 。

1. 启动图黑边问题

• • 问题描述：设置启动图后屏幕上下可能会有黑边。

• • 解决办法：在 manifest.json 源码视图的 "app-plus" 中配置 "splashscreen" : {"androidStyle" : "common","iosStyle" : "common"} 。

1. 证书错误问题

• • 问题描述：无法在当前的 Mac 电脑上找到指定的证书文件，导致打包失败。

• • 解决办法：

• • • 安装证书：在开发过程中，从苹果开发者官网购买并安装合格的开发者证书。

• • • 更新证书：如果证书已过期或被吊销，及时更新。

• • • 删除关闭的证书：在系统钥匙串中删除关闭的证书，并重新安装开发者证书。

1. iOS 安装不了问题

• • 问题描述：应用程序签名不正确，导致无法在 iOS 设备上安装和运行。

• • 解决办法：

• • • 检查证书和描述文件设置是否正确，如有错误，重新设置。

• • • 重新打包应用程序，确保证书和描述文件正确设置且未过期。

• • • 清空 iOS 设备缓存，重新尝试安装。

• • • 卸载原有应用程序，重新安装新的应用程序。

（二）安卓平台常见问题与解决方法

1. 内嵌到安卓中遇到的问题

• • 问题描述：如打不开uniapp项目、图片样式加载失败、item点击事件失效、页面显示不完全等。

• • 解决办法：

• • • 对于打不开项目，尝试 clean projects 然后 rebuild projects 。

• • • 图片加载失败和 item 点击失效问题，可在加载接口数据时设置适时的 setTimeout ，去掉热更新逻辑，每次打包测试时删除真机中原来的 app 应用，重新打包生成。

• • • 页面显示不完全问题，修改获取页面长度的方法，动态变化 scrollview 的长度。

1. 跳转问题

• • 问题描述：涉及路由跳转、子页面跳转、tabbar 跳转、导航栏跳转时可能出现错误。

• • 解决办法：

• • • 路由跳转使用 uni.navigateTo 方法，保持页面路径正确。

• • • 子页面跳转加上页面路径前缀。

• • • tabbar 跳转使用 uni.switchTab 方法，并设置对应选项卡高亮。

• • • 导航栏跳转在组件中加上 open-type 属性。

1. 证书与打包相关问题

• • 问题描述：如证书申请与配置错误、打包兼容问题、安装/更新失败等。

• • 解决办法：

• • • 按照正确流程申请证书，包括生成证书请求文件、申请开发证书和发布证书等，并进行相应配置。

• • • 解决打包兼容问题，如勾选支持的 CPU 类型。

• • • 对于安装/更新失败，保证旧版和新版 APP 的签名一致。

（三）小程序平台常见问题与解决方法

1. 编译错误

• • 问题描述：可能是代码中存在语法错误或逻辑错误。

• • 解决办法：检查代码并修复错误。

1. 打包失败

• • 问题描述：资源文件缺失或配置文件错误。

• • 解决办法：检查相关文件并重新打包。

1. 运行异常

• • 问题描述：代码中存在 bug 或兼容性问题。

• • 解决办法：进行调试和修复。

1. 其他异常

• • 问题描述：环境配置不正确或网络连接问题。

• • 解决办法：进行排查和解决。

1. 特定问题

• • 如 canvas 绘图太大生成图片失败，可降低清晰度，调整宽高比。

• • 调试工具出现白色框框，清理缓存，重新打开项目。

• • 全面屏底部安全区域问题，使用有空间占位的元素作为底部展示。

• • 部分图片在手机不能正常展示，减少背景图使用，使用 image 标签代替。

• • 体验版使用请求失败，打开开发调试，重新打开体验版。

• • webview 下拉影响内部拖拽滑动，在最外层使用 @touchmove.prevent="() => {}" 进行阻止行为。

---

请注意，在实际开发过程中，应根据具体情况灵活运用上述解决方法，并及时查阅官方文档和社区资源，以获取更准确和最新的解决方案。