跳到主要内容
教程目录

uni-app 离线打包 iOS 保姆级教程，Windows 本地出 ipa 不排队

这篇带你在 Windows 上把一个 uni-app 项目本地打包成 iOS App，从导出 Xcode 工程、装到 iPhone 上运行，一直做到出 ipa 上传 App Store Connect。适合已经在 HBuilderX 里开发 uni-app、想摆脱云打包排队的开发者。你需要准备 Apple 开发者账号、一台 iPhone 和数据线，并且已经安装 KXBuild，第一次走完全程大约一小时，之后每次重打几分钟。

为什么要本地打包

HBuilderX 的云打包省去了自己配 Xcode 的麻烦，但项目进入频繁调试阶段后，下面几件事会越来越明显。

  • 高峰期要排队，等一次包短则几分钟，长则更久。
  • 云打包有次数限制，调试原生功能时很容易用完。
  • 改一次 manifest.json 里的原生配置，比如权限描述、模块、图标，就要重新打一次自定义基座或正式包。

本地打包把这一步搬回自己电脑上。DCloud 官方的离线打包本来要求在 Mac 上用 Xcode 完成，用 KXBuild 可以在 Windows 上完成同样的事，导出、编译、装机、出 ipa 都在本机，打多少次都不用排队。

准备离线 SDK 和 AppKey

下载 iOS 离线 SDK

到 DCloud 的 iOS 离线 SDK 下载页 下载 SDK 并解压，解压后的根目录下有 HBuilder-Hello、SDK 两个文件夹和 uniapp.podspec 文件，导出时选的就是这个根目录，例如 D:\sdk\HBuilder-iOS-SDK。KXBuild 支持 HBuilderX 5.13 起的离线 SDK，这些版本的 SDK 用 CocoaPods 集成原生模块。

SDK 版本要和你的 HBuilderX 版本一致。 两边版本不同，App 启动后会提示版本不匹配或者白屏。升级 HBuilderX 之后记得同时换新的 SDK。

申请离线打包 AppKey

DCloud 离线 SDK 启动时会校验 AppKey，没有它 App 一打开就报 AppKey 错误。AppKey 和 Bundle ID 绑定，先想好 App 的 Bundle ID（例如 com.example.myapp），它也要和你在 Apple 开发者后台注册的 App ID 一致。

登录 DCloud 开发者中心 dev.dcloud.net.cn，在「我的应用」里打开这个 uni-app 应用，进入「各平台信息」新增 iOS 平台，填写 Bundle ID，保存后就能查看离线打包 Key。

在 Apple 开发者后台注册 App ID

登录 developer.apple.com，在「Certificates, Identifiers & Profiles」的 Identifiers 里新建一个 App ID，Bundle ID 填上面同一个。用到推送、Apple 登录、关联域名这类能力的，在这里勾上对应的 Capability，之后生成的描述文件才会带上这些权限。manifest.json 里声明的 iOS capabilities 导出时会写进工程的 entitlements，两边要对得上。

在 HBuilderX 里配好 manifest.json

导出时会读取 manifest.json 里的 App 配置，下面几项在 HBuilderX 的可视化界面里改好，之后每次导出都会自动带上。

  • 应用名称、版本名称、版本号。版本号每次上传 App Store Connect 都要比上一次大。
  • 「App 图标配置」里用一张 1024×1024 的图自动生成全部 iOS 图标。
  • 「App 权限配置」里填 iOS 隐私信息访问的许可描述，用到相机、相册、定位时必须填，否则调用时 App 会闪退，审核也会被拒。
  • 「App 模块配置」里勾选用到的模块，例如支付、推送、地图，并填好各自的参数，导出时会用 CocoaPods 装好对应的 SDK 库。

导出 Xcode 工程

导出会先调用 HBuilderX 编译页面，再和离线 SDK 一起生成一个 Xcode 工程。导出前先打开 HBuilderX，这时会自动找到它；HBuilderX 没开时，桌面上有它的文件夹或快捷方式也能找到，都没有时命令行用 –hbx 指定安装目录。编译页面前 HBuilderX 要登录 DCloud 账号，manifest.json 的 AppID 要在「基础配置」里获取过。

Vue 2 项目的 HBuilderX 不能装在带括号的目录，例如 C:\Program Files (x86)\HBuilderX，这是 HBuilderX 自身编译插件的限制。把 HBuilderX 整个文件夹挪到 D:\HBuilderX 这样的目录，或者在 manifest.json 里改用 Vue 3。

以下两种做法任选其一。

用 VS Code 插件导出

按 Ctrl+Shift+P 打开命令面板，运行 KXBuild: 导入 uni-app 项目，依次选择 uni-app 工程目录（含 manifest.json 的那一层）、离线 SDK 根目录和输出目录，再填写 Bundle ID 和 DCloud App Key。导出在终端中执行，完成后在 VS Code 中打开输出目录。

用命令行导出

1uniapp2xcode --project D:\work\myuniapp --sdk D:\sdk\HBuilder-iOS-SDK --output D:\work\myuniapp-ios --bundle-id com.example.myapp --dcloud-appkey 你的AppKey --clean

–clean 表示先清空输出目录再导出，输出目录已存在时必须加。其余参数，例如 –display-name、–version-name、–team-id，见 uniapp2xcode 命令参考。导出完成后，生成的工程在 D:\work\myuniapp-ios\HBuilder-Hello\HBuilder-Hello.xcworkspace，在 VS Code 中「文件 → 打开文件夹」打开 D:\work\myuniapp-ios 即可。

把 Bundle ID 和 AppKey 写进 uni-app 工程

每次导出都要填 Bundle ID 和 AppKey 比较麻烦。在 uni-app 工程里建 nativeResources\ios\Info.plist，写上 CFBundleIdentifier 和 dcloud_appkey 两项，之后导出时这两项可以留空，插件和命令行都会从这里读取。这个 Info.plist 里的其他键也会在每次导出时合并进 iOS 工程的 Info.plist。

 1<?xml version="1.0" encoding="UTF-8"?>
 2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 3<plist version="1.0">
 4<dict>
 5  <key>CFBundleIdentifier</key>
 6  <string>com.example.myapp</string>
 7  <key>dcloud_appkey</key>
 8  <string>你的AppKey</string>
 9</dict>
10</plist>

这个文件可以直接用 VS Code 打开，KXBuild 的属性列表编辑器按表格显示和编辑。

体检

导出后第一次编译前先做一次体检，它会检查编译需要的环境并修好缺的部分。以下两种做法任选其一。

  • VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
  • 命令行。运行下面的命令。
1kxbuild doctor D:\work\myuniapp-ios\HBuilder-Hello\HBuilder-Hello.xcworkspace

检查图标

导出后 App 图标在 HBuilder-Hello\HBuilder\Images.xcassets 里。在 VS Code 资源管理器中右键这个 .xcassets 文件夹，选择「KXBuild: 打开资源目录」，可以看到每个尺寸的图标是否都有。点标题栏的「KXBuild: 编译检查资源目录」，缺少的尺寸和 App Store 图标带透明通道这类问题会列在「问题」面板里。

资源目录编辑器中查看 App 图标

图标要改就回 HBuilderX 的「App 图标配置」里改，然后重新导出。 直接在导出目录里改，下次带 –clean 导出时会被覆盖。

连接 iPhone 并真机运行

真机运行需要签名。先在 Apple 开发者后台创建 Apple Development 证书和包含这台 iPhone 的 Development 描述文件，把 .p12 和 .mobileprovision 放进证书目录，做法见证书与签名。

用数据线连上 iPhone。第一次连接时 KXBuild 视图的设备节点如果提示「点击配置」，点一下安装设备驱动。手机上解锁并点「信任此电脑」，再到「设置 → 隐私与安全性 → 开发者模式」打开开发者模式，手机会重启一次。详细说明见设备准备。

在 KXBuild 视图中选中这台 iPhone，按 F5。KXBuild 会依次完成构建、签名、安装和启动，App 在手机上打开后，原生层可以在 VS Code 中打断点，页面 JS 用 HBuilderX 自带的调试工具，两边互不影响。第一次调试某个 iOS 版本时会自动下载符号库，有几个 GB，只需要一次。

改了前端代码之后怎么更新

页面、样式、JS 照常在 HBuilderX 里写。导出的 iOS 工程里是页面的编译结果，改完代码重新导出一次，改动才会进入 App。导出时发现源码比上次编译的结果新，会自动重新编译页面。

  1. 重新运行一次导出，插件就是再运行一次 KXBuild: 导入 uni-app 项目，命令行就是再执行一次同一条 uniapp2xcode 命令。
  2. 回到 VS Code 按 F5。

manifest.json 里的原生配置（权限描述、模块、图标、版本号）改完同样重新导出即可，不需要重新打自定义基座，也不需要等云打包。不同改动要做的事如下。

改了什么 要做什么
页面、样式、JS 重新导出，按 F5
manifest.json 的原生配置 重新导出，按 F5
nativeResources\ios\Info.plist 重新导出，按 F5
升级了 HBuilderX 换同版本的离线 SDK，重新导出，按 F5

重新导出会清空输出目录，不要在导出目录里手改文件，要保留的配置都放回 uni-app 工程的 manifest.json 或 nativeResources 里。

打包 ipa 并上架

上架前准备好三样东西。Apple 开发者后台的 Apple Distribution 证书、App Store 类型的描述文件，都放进证书目录。App Store Connect 里新建好这个 App，Bundle ID 和工程里的一致。

在 HBuilderX 里把版本号调大并重新导出，然后用 Release 配置构建。以下两种做法任选其一。

  • VS Code 插件。在 KXBuild 视图的「构建配置」节点切到 Release，命令面板运行 KXBuild: 构建。
  • 命令行。运行下面的命令。
1kxbuild build D:\work\myuniapp-ios\HBuilder-Hello\HBuilder-Hello.xcworkspace -s HBuilder -c Release

构建完成后，工程目录下的 build 文件夹里就是可以上传的 .ipa。Release 配置没有指定 Apple Distribution 证书时，命令行加 -D CODE_SIGN_IDENTITY=“Apple Distribution” 临时覆盖。

在 Windows 上用 Appuploader 登录开发者账号上传这个 ipa，Apple 处理完后它会出现在 App Store Connect 的 TestFlight 页，先装到自己手机上确认，再在「App Store」页选择这个构建提交审核。完整步骤见发布与上架。

常见问题

App 一打开就提示 AppKey 错误

导出时没有提供 AppKey，或者 AppKey 申请时填的 Bundle ID 和工程里的不一致。在 DCloud 开发者中心核对 iOS 平台的包名，重新导出。

启动后提示版本不匹配或白屏

离线 SDK 和 HBuilderX 版本不一致。下载与当前 HBuilderX 同版本的 SDK，重新导出。

导出时提示找不到 HBuilderX

先打开 HBuilderX 再导出。还找不到时，命令行加 –hbx 指定 HBuilderX 的安装目录，也就是 cli.exe 所在的目录。

导出时提示未登录或 AppID 不存在

HBuilderX 编译页面需要登录 DCloud 账号。在 HBuilderX 里登录，再打开 manifest.json 的「基础配置」，AppID 旁点「获取」或「重新获取」，然后重新导出。

导出结束时提示有模块被跳过

当前离线 SDK 里没有这个模块，或者模块自带的库链接不了，例如 5.26 版 SDK 的实人认证缺少依赖库。其他模块照常打包，被跳过的模块要等 DCloud 发布修复后的 SDK。

调用相机或相册时闪退

Info.plist 里缺少对应的隐私描述。在 HBuilderX「App 权限配置」里补上 iOS 隐私信息访问的许可描述，或写进 nativeResources\ios\Info.plist，然后重新导出。

装到手机失败

多数是签名问题，描述文件里没有这台手机的 UDID，或者证书类型不对。按证书与签名检查，其他错误见排错与 FAQ。