Cordova iOS 打包：Windows 上用 Cordova、Ionic 打 ipa 并真机调试
最后更新
Cordova iOS 打包可以在 Windows 上完成：cordova platform add ios 生成 platforms\ios 下的工程后，构建、安装和调试交给 KXBuild。做法是在 config.xml 里写好 Bundle ID、版本号和权限说明，运行体检，连上 iPhone 按 F5 调试网页和原生代码，最后用 Release 配置打出能上传 App Store Connect 的 ipa，Ionic 的 Cordova 工程同样适用。
你需要 Apple 开发者账号、一台 iPhone 和数据线，并且已经安装 KXBuild。
cordova build ios 为什么在 Windows 上用不了？
cordova platform add ios 在 Windows 上可以执行，它生成 platforms\ios 下的 Xcode 工程。但 cordova build ios 和 cordova run ios 要调 Xcode 的构建工具，只能在 macOS 上运行。
用 KXBuild 之后，iOS 端的构建、安装和调试交给 KXBuild，其他 cordova 命令照常使用。cordova create、cordova plugin add、cordova prepare 不受影响，Android 端也照旧用 cordova build android。
第 1 步：怎么新建 Cordova 工程并添加 iOS 平台？
已有工程在工程目录添加 iOS 平台，之后在 VS Code 中「文件 → 打开文件夹」打开 platforms\ios 目录即可。没有现成工程的，先用 npm 安装 Cordova，创建工程，进入工程目录再添加 iOS 平台。platform add 不在工程目录里执行会报错。
1npm install -g cordova
2cd D:\work
3cordova create MyApp com.example.myapp MyApp
4cd MyApp
5cordova platform add ios
cordova create 的第二个参数是 Bundle ID，第三个是 App 名。Bundle ID 改成你自己的域名反写，之后在 Apple 开发者后台注册 App ID 用同一个。
当前的 cordova-ios 生成的工程固定叫 App，platforms\ios 下有 App.xcodeproj 和 App.xcworkspace，构建统一用 App.xcworkspace。依赖默认用 Swift Package 管理，不需要 CocoaPods。
Ionic 工程怎么做 iOS 打包？
Ionic 新建工程默认集成 Capacitor，要用 Cordova 的话在 ionic start 时加 –cordova。先装 Ionic CLI 和 Cordova，再新建。
1npm install -g @ionic/cli cordova
2cd D:\work
3ionic start myApp tabs --type=angular --cordova --package-id=com.example.myapp
4cd myApp
5ionic cordova platform add ios
之后把本文里的 cordova 命令换成对应的 ionic cordova 命令即可，比如 cordova prepare ios 换成 ionic cordova prepare ios。区别是 ionic cordova prepare 会先执行一次 Ionic 构建，把网页代码编译到 www，再同步到 platforms\ios。已有的 Ionic Cordova 工程直接在工程目录执行 ionic cordova platform add ios。
第 2 步：config.xml 里的 iOS 配置怎么写？
Cordova 的 iOS 工程按 config.xml 生成和更新，Bundle ID、版本号、权限说明都在这里改，每次 prepare 时写进 platforms\ios。直接改 platforms\ios 里的同名配置，下次 prepare 可能被覆盖。
1<widget id="com.example.myapp" version="1.0.0" ios-CFBundleVersion="1"
2 xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
3 <name>MyApp</name>
4 <platform name="ios">
5 <preference name="deployment-target" value="13.0" />
6 <edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
7 <string>用于拍摄头像</string>
8 </edit-config>
9 </platform>
10</widget>
各项的作用如下。
| 配置 | 作用 |
|---|---|
id |
Bundle ID，要和开发者后台注册的 App ID、描述文件一致 |
version |
商店里显示的版本号 |
ios-CFBundleVersion |
构建号，每次上传 App Store Connect 都要比上一次大 |
name |
App 名，也是 ipa 的文件名 |
deployment-target |
支持的最低 iOS 版本 |
edit-config |
往 Info.plist 里写键，权限说明放在这里 |
用到相机、相册、定位、麦克风的 App 必须写对应的权限说明，缺了的话一调用就闪退，审核也会被拒。改完 config.xml 执行一次 cordova prepare ios。
签名用的证书和描述文件放进证书目录，开发阶段用 Apple Development 证书和包含这台 iPhone 的 Development 描述文件，做法见证书与签名。
插件带 CocoaPods 依赖怎么办？
插件照常用 cordova plugin add 添加，例如相机插件。
1cordova plugin add cordova-plugin-camera
多数插件以 Swift Package 或源码的方式加进工程，加完就能构建。插件带 CocoaPods 依赖时，platforms\ios 下会出现 Podfile，Windows 上 Cordova 不会自动安装，要在 platforms\ios 目录执行一次 pod install。之后每次增删这类插件都要重新执行。
1cd platforms\ios
2pod install
CocoaPods 的更多用法见 CocoaPods。
第 3 步：运行体检
添加平台和插件之后运行一次体检，它会检查编译需要的环境，并准备好 iOS 端的工程。以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
- 命令行。在 Cordova 工程目录运行下面的命令。
1kxbuild doctor .\platforms\ios\App.xcworkspace
第 4 步：怎么在 iPhone 上运行 Cordova App？
在 VS Code 中打开 platforms\ios 目录，KXBuild 视图会列出 App 工程。用数据线连上 iPhone，第一次连接要安装 Apple 设备驱动、在手机上点「信任此电脑」、打开开发者模式，做法见设备准备。然后在 KXBuild 视图的「设备」节点下点一下这台 iPhone，选为当前设备，按 F5。
KXBuild 会依次构建、签名、安装、启动 App 并接上调试器。第一次调试某个 iOS 版本时会自动下载符号库，有几个 GB，只需要一次，进度显示在通知里。
网页代码改完怎么同步到 iOS 工程？
网页代码照常在工程根目录的 www 下编写。改完之后执行 cordova prepare ios，把 www、config.xml 和插件的改动同步到 platforms\ios，再停止调试、重新按 F5。
1cd D:\work\MyApp
2cordova prepare ios
不要直接改 platforms\ios\www 里的文件，下次 prepare 会被覆盖。调试工具栏上的「重启」不会重新构建，同步之后要用 F5。
怎么在真机调试网页和原生代码？
一个 Cordova App 里有两种代码，各用各的调试方式。
- 原生代码。插件的 Objective-C、Swift 源码和 App 目录下的原生代码在 VS Code 中打断点，F5 启动后直接生效，变量、调用栈、调试控制台都是标准的调试视图，用法见运行与调试。
- 网页代码。页面逻辑先在桌面浏览器里用开发者工具调好，这部分和手机上的行为基本一致。只在 iPhone 上出现的问题，在 Debug 包里临时引入 vConsole 或 Eruda 这类页面内调试面板，直接在手机上看 console 输出、报错和网络请求，发布前去掉。手边有 Mac 时，Debug 包的 WebView 也可以用 Safari 的网页检查器连上。
调用原生插件出问题时，在插件的原生方法里打断点，从 JS 调一次，就能看到传进原生的参数和返回值。App 的原生日志和崩溃信息在「输出 → KXBuild Console」，构建日志在「输出 → KXBuild」。
第 5 步：怎么打包 Release ipa？
上架前先在 config.xml 里改 version 和 ios-CFBundleVersion，执行 cordova prepare ios。证书目录里要有 Apple Distribution 证书和 App Store 类型的描述文件。以下两种做法任选其一。
- VS Code 插件。在命令面板或工程的右键菜单运行 KXBuild: 生成 App Store ipa。
- 命令行。在 Cordova 工程目录运行下面的命令。
1kxbuild build .\platforms\ios\App.xcworkspace -c Release --export app-store
--export app-store 不管工程里设的是哪种证书，都用证书目录里的 Apple Distribution 证书和 App Store 描述文件签名。提示找不到 App Store 描述文件时，把 App Store 类型的 .mobileprovision 放进证书目录，Distribution 证书的 .p12 也放进去，密码写在 password.properties 里。
构建完成后得到 platforms\ios\build\MyApp.ipa，文件名是 config.xml 里的 name。在 Windows 上用 Appuploader 上传到 App Store Connect，处理完成后在 TestFlight 里装到手机上验证，再提交审核，详见发布与上架。
审核对只包一层网页、没有 App 特有功能的应用比较严格，提交前确认 App 用到了原生能力或提供了网页做不到的体验。按上面五步走，Cordova iOS 打包和真机调试都在 Windows 上完成，更多说明见 Cordova iOS 开发。
常见问题
cordova platform add ios 报找不到工程怎么办？
原因是不在 Cordova 工程目录里执行，进入工程目录再执行即可。先 cd 进 cordova create 生成的目录（config.xml 所在的目录），再执行 platform add。
改了网页或 config.xml，手机上为什么没变化？
通常是没有执行 cordova prepare ios，或者执行后没有重新按 F5。Ionic 工程用 ionic cordova prepare ios，它会先重新编译网页代码。
编译报找不到插件的头文件或模块怎么办？
在 platforms\ios 执行一次 pod install 即可，原因是插件带 CocoaPods 依赖但还没安装。安装完之后重新构建 App.xcworkspace。
调用相机或相册时 App 为什么闪退？
因为 Info.plist 里缺权限说明。按上面的写法在 config.xml 里加 edit-config，执行 cordova prepare ios 后重新按 F5。