uni-app 离线打包 iOS 教程：Windows 本地打 uni-app ipa，不用云打包排队
最后更新
uni-app 离线打包 iOS 可以在 Windows 本地完成：装好 KXBuild 的 HBuilderX 插件，导入同版本的离线 SDK、填好 AppKey 和证书，就能运行到 iPhone 真机，改完页面几秒推送到手机，最后生成可上传 App Store Connect 的 ipa，不用云打包排队。需要 Apple 开发者账号、iPhone 和数据线，并已安装 KXBuild，第一次约一小时。
为什么要在本地做 uni-app 离线打包 iOS？
HBuilderX 的云打包省去了自己配 Xcode 的麻烦，但项目进入频繁调试阶段后，下面几件事会越来越明显。
- 高峰期要排队，等一次包短则几分钟，长则更久。
- 云打包有次数限制，调试原生功能时很容易用完。
- 改一次 manifest.json 里的原生配置，比如权限描述、模块、图标，就要重新打一次自定义基座或正式包。
本地打包把这一步搬回自己电脑上。DCloud 官方的离线打包本来要求在 Mac 上用 Xcode 完成，用 KXBuild 可以在 Windows 上完成同样的事，编译、装机、出 ipa 都在本机，打多少次都不用排队。
离线 SDK 和 AppKey 怎么准备？
下载 iOS 离线 SDK
到 DCloud 的 iOS 离线 SDK 下载页 下载 SDK 的 zip，不用解压，第一次运行时插件会让你选这个 zip。KXBuild 支持 HBuilderX 5.13 起的离线 SDK。
SDK 版本要和你的 HBuilderX 版本一致。 两边版本不同，App 启动后会提示版本不匹配或者白屏。每个 HBuilderX 版本只需导入一次，升级 HBuilderX 之后记得导入新版本的 SDK。
申请离线打包 AppKey
DCloud 离线 SDK 启动时会校验 AppKey，没有它 App 一打开就报 AppKey 错误。AppKey 和 Bundle ID 绑定，先想好 App 的 Bundle ID（例如 com.example.myapp），它也要和你在 Apple 开发者后台注册的 App ID 一致。
登录 DCloud 开发者中心，在「应用管理」里打开这个 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，两边要对得上。
manifest.json 里要配好哪些项？
打包时会读取 manifest.json 里的 App 配置，下面几项在 HBuilderX 的可视化界面里改好，之后每次运行都会自动带上。
- 「基础配置」里登录 DCloud 账号后获取 AppID，没有 AppID 页面编译不了。
- 应用名称、版本名称、版本号。版本号每次上传 App Store Connect 都要比上一次大。
- 「App 图标配置」里用一张 1024×1024 的图自动生成全部 iOS 图标。
- 「App 权限配置」里填 iOS 隐私信息访问的许可描述，用到相机、相册、定位时必须填，否则调用时 App 会闪退，审核也会被拒。
- 「App 模块配置」里勾选用到的模块，例如支付、推送、地图，并填好各自的参数，打包时会用 CocoaPods 装好对应的 SDK 库。
Vue 2 项目的 HBuilderX 不能装在带括号的目录，例如 C:\Program Files (x86)\HBuilderX，这是 HBuilderX 自身编译插件的限制。把 HBuilderX 整个文件夹挪到 D:\HBuilderX 这样的目录，或者在 manifest.json 里改用 Vue 3。
HBuilderX 插件怎么安装？
- 装完 KXBuild 后运行一次
kxbuild doctor，它会检查并装好编译需要的环境；电脑上已有 HBuilderX 时，插件也会一起装好。以后再运行kxbuild doctor会把插件更新到最新版。 - 完全退出 HBuilderX 再重新打开。
如果后面说的菜单没有出现，在 uni-app 技术栈页下载 kxbuild-hbuilderx-plugin.zip，解压到 HBuilderX 安装目录下的 plugins 文件夹，得到 plugins\kxbuild-hbuilderx-plugin，再重新打开 HBuilderX。
装好后，在项目管理器里右键 uni-app 项目，会多出「KXBuild iOS」菜单；选中项目后，顶部「运行」「发行」菜单里也会出现带 (KXBuild) 的命令。
怎么第一次运行到 iPhone 真机？
真机运行需要签名。先在 Apple 开发者后台创建 Apple Development 证书和包含这台 iPhone 的 Development 描述文件，把 .p12 和 .mobileprovision 放进证书目录，做法见Windows 给 iOS App 签名。
用数据线连上 iPhone。手机上解锁并点「信任此电脑」，再到「设置 → 隐私与安全性 → 开发者模式」打开开发者模式，手机会重启一次。详细说明见设备准备。
在项目管理器选中项目，点「运行 → 运行到 iPhone 真机 (KXBuild)」。第一次会依次问两件事，之后不再询问。
- Bundle ID 与离线打包 AppKey：填上面申请 AppKey 时用的 Bundle ID 和 AppKey。它们保存在项目的 nativeResources\ios\Info.plist，以后要改，右键项目 →「KXBuild iOS」→「设置 Bundle ID 与 AppKey」。
- iOS 离线 SDK：选择下载好的 SDK zip。以后换 SDK，右键项目 →「KXBuild iOS」→「导入 iOS 离线 SDK」。
接着插件会编译页面、生成 iOS 工程、编译 App，装到手机上并启动，进度显示在 HBuilderX 的控制台里，第一次大约一两分钟。
nativeResources\ios\Info.plist 里的其他键也会在每次运行时合并进 App 的 Info.plist，例如 manifest.json 里没有的权限描述可以直接写在这里。这个文件可以用 VS Code 打开，KXBuild 的属性列表编辑器按表格显示和编辑。
改了前端代码之后怎么更新？
页面、样式、JS 照常在 HBuilderX 里写。改完之后按改动选命令。
| 改了什么 | 要做什么 |
|---|---|
| 页面、样式、JS | 运行 → 推送页面到 iPhone (KXBuild)，几秒生效，App 数据保留 |
| manifest.json 的原生配置（模块、权限、图标、版本号） | 运行 → 运行到 iPhone 真机 (KXBuild) |
| nativeResources\ios\Info.plist | 运行 → 运行到 iPhone 真机 (KXBuild) |
| 升级了 HBuilderX | 导入同版本的离线 SDK，再运行到 iPhone 真机 |
| 换了一台 iPhone | 运行到 iPhone 真机 |
「推送页面到 iPhone」只替换手机上 App 的页面再重新启动，不重新安装，登录状态和本地存储都还在。「运行到 iPhone 真机」时如果页面也变了，会先卸载旧版本再安装，App 的本地数据会被清除，所以只改页面时用推送更省事。
原生配置改完重新运行即可，不需要重新打自定义基座，也不需要等云打包。
需要原生断点时怎么用 VS Code？
页面 JS 用 HBuilderX 自带的调试工具。要在原生层设断点，或者检查图标，用 VS Code 打开项目里的 unpackage\kxbuild 文件夹，这是插件运行时生成的 Xcode 工程。
- 断点调试：在 KXBuild 视图中选中这台 iPhone，按 F5，App 在手机上打开后就能在原生代码里打断点。第一次调试某个 iOS 版本时会自动下载符号库，有几个 GB，只需要一次。页面改动仍然在 HBuilderX 里推送，VS Code 里按 F5 重新安装不会更新页面。
- 检查图标：App 图标在 HBuilder-Hello\HBuilder\Images.xcassets 里。在资源管理器中右键这个 .xcassets 文件夹，选择「KXBuild: 打开资源目录」，可以看到每个尺寸的图标是否都有。点标题栏的「KXBuild: 编译检查资源目录」，缺少的尺寸和 App Store 图标带透明通道这类问题会列在「问题」面板里。
不要在 unpackage\kxbuild 里手改文件，下次运行时会被覆盖。图标回 HBuilderX 的「App 图标配置」里改，其他要保留的配置放回 manifest.json 或 nativeResources 里。
怎么打出 uni-app ipa 并上架？
上架前准备好三样东西。Apple 开发者后台的 Apple Distribution 证书、App Store 类型的描述文件，都放进证书目录。App Store Connect 里新建好这个 App，Bundle ID 和项目里的一致。
在 HBuilderX 里把版本号调大，然后点「发行 → 生成 iOS App Store ipa (KXBuild)」。插件用 Release 配置编译，用 Apple Distribution 证书和 App Store 描述文件签名，ipa 生成在项目的 unpackage\release\ipa 下，以应用名称命名。
在 Windows 上用 Appuploader 登录开发者账号上传这个 ipa，Apple 处理完后它会出现在 App Store Connect 的 TestFlight 页，先装到自己手机上确认，再在「App Store」页选择这个构建提交审核。完整步骤见发布与上架。
不用插件，怎么在命令行打包？
要在脚本或持续集成里打包时，可以直接用命令行。在 uni-app 项目目录下运行，前两条只需一次。
1uniapp2xcode sdk import D:\Downloads\iOS-SDK.zip
2uniapp2xcode config --project . --bundle-id com.example.myapp --dcloud-appkey 你的AppKey
3uniapp2xcode --project . --sdk auto --output .\unpackage\kxbuild --update
4kxbuild build .\unpackage\kxbuild\HBuilder-Hello\HBuilder-Hello.xcworkspace -s HBuilder -c Release --export app-store
第三条导出 Xcode 工程，–update 表示只改了页面时只替换页面，几秒完成。第四条用 Release 配置构建并按 App Store 的要求签名，ipa 生成在 unpackage\kxbuild\HBuilder-Hello\build 下。
命令行导出时要先打开 HBuilderX，它会被自动找到；找不到时加 –hbx 指定安装目录。其余参数见 uniapp2xcode 命令参考。插件和命令行走的是同一套 uni-app 离线打包 iOS 流程，打出的 ipa 一样可以上传 App Store Connect。
常见问题
右键和顶部菜单里没有 KXBuild 的命令怎么办？
顶部菜单的命令要先在项目管理器里选中 uni-app 项目才会出现。右键菜单也没有时，确认 plugins\kxbuild-hbuilderx-plugin 下直接是 package.json，没有多套一层文件夹，然后完全退出并重新打开 HBuilderX。
App 一打开就提示 AppKey 错误怎么办？
AppKey 没填，或者申请 AppKey 时填的 Bundle ID 和插件里填的不一致。在 DCloud 开发者中心核对 iOS 平台的包名，再右键项目 →「KXBuild iOS」→「设置 Bundle ID 与 AppKey」改好，重新运行到 iPhone 真机。
启动后提示版本不匹配或白屏怎么办？
离线 SDK 和 HBuilderX 版本不一致。下载与当前 HBuilderX 同版本的 SDK，右键项目 →「KXBuild iOS」→「导入 iOS 离线 SDK」，再运行到 iPhone 真机。
提示未登录或 AppID 不存在怎么办？
HBuilderX 编译页面需要登录 DCloud 账号。在 HBuilderX 里登录，再打开 manifest.json 的「基础配置」，AppID 旁点「获取」或「重新获取」，然后重新运行。
改了页面，手机上还是旧页面怎么办？
用「推送页面到 iPhone」或「运行到 iPhone 真机」更新。只在 VS Code 里按 F5 重新安装不会更新页面。
为什么运行后 App 的登录状态和本地存储没了？
页面有变化时，「运行到 iPhone 真机」会卸载旧版本再安装。只改了页面时用「推送页面到 iPhone」，数据会保留。
提示有模块被跳过怎么办？
当前离线 SDK 里没有这个模块，或者模块自带的库链接不了，例如 5.26 版 SDK 的实人认证缺少依赖库。其他模块照常打包，被跳过的模块要等 DCloud 发布修复后的 SDK。
调用相机或相册时闪退怎么办？
Info.plist 里缺少对应的隐私描述。在 HBuilderX「App 权限配置」里补上 iOS 隐私信息访问的许可描述，或写进 nativeResources\ios\Info.plist，然后重新运行到 iPhone 真机。
装到手机失败怎么办？
多数是签名问题，描述文件里没有这台手机的 UDID，或者证书类型不对。按证书与签名检查，其他错误见排错与 FAQ。