Cordova 与 Ionic 在 Windows 上打 iOS 包并真机调试
这篇带你在 Windows 上把 Cordova 或 Ionic 工程打成 iOS App，装到 iPhone 上调试，最后打出能上传 App Store Connect 的 ipa。适合用 Web 技术做 App、在 Windows 上开发的开发者。你需要 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。
新建 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 的做法
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。
在 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 描述文件，做法见证书与签名。
添加插件
插件照常用 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。
体检
添加平台和插件之后运行一次体检，它会检查编译需要的环境，并准备好 iOS 端的工程。以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
- 命令行。在 Cordova 工程目录运行下面的命令。
1kxbuild doctor .\platforms\ios\App.xcworkspace
在 iPhone 上运行
在 VS Code 中打开 platforms\ios 目录，KXBuild 视图会列出 App 工程。用数据线连上 iPhone，第一次连接要安装 Apple 设备驱动、在手机上点「信任此电脑」、打开开发者模式，做法见设备准备。然后在 KXBuild 视图的「设备」节点下点一下这台 iPhone，选为当前设备，按 F5。
KXBuild 会依次构建、签名、安装、启动 App 并接上调试器。第一次调试某个 iOS 版本时会自动下载符号库，有几个 GB，只需要一次，进度显示在通知里。
网页代码改完怎么同步
网页代码照常在工程根目录的 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」。
打包 Release ipa
上架前先在 config.xml 里改 version 和 ios-CFBundleVersion，执行 cordova prepare ios。证书目录里要有 Apple Distribution 证书和 App Store 类型的描述文件。以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图的「构建配置」节点切到 Release，命令面板运行 KXBuild: 构建。
- 命令行。在 Cordova 工程目录运行下面的命令。
1kxbuild build .\platforms\ios\App.xcworkspace -c Release
工程的 Release 配置没有指定发布证书时，命令行加 -D CODE_SIGN_IDENTITY="Apple Distribution" 临时覆盖。
构建完成后得到 platforms\ios\build\MyApp.ipa，文件名是 config.xml 里的 name。在 Windows 上用 Appuploader 上传到 App Store Connect，处理完成后在 TestFlight 里装到手机上验证，再提交审核，详见发布与上架。审核对只包一层网页、没有 App 特有功能的应用比较严格，提交前确认 App 用到了原生能力或提供了网页做不到的体验。
常见问题
cordova platform add ios 报找不到工程
不在 Cordova 工程目录里执行。先 cd 进 cordova create 生成的目录（config.xml 所在的目录），再执行 platform add。
改了网页或 config.xml，手机上没变化
没有执行 cordova prepare ios，或者执行后没有重新按 F5。Ionic 工程用 ionic cordova prepare ios，它会先重新编译网页代码。
编译报找不到插件的头文件或模块
插件带 CocoaPods 依赖，但没有在 platforms\ios 执行 pod install。安装完之后重新构建 App.xcworkspace。
调用相机或相册时 App 闪退
Info.plist 里缺权限说明。按上面的写法在 config.xml 里加 edit-config，执行 cordova prepare ios 后重新按 F5。