这篇从新建一个 Expo 工程开始，在 Windows 本机生成 iOS 工程，装到 iPhone 上跑开发版，最后打出能上传 App Store Connect 的 ipa。你需要 Apple 开发者账号、一台 iPhone 和数据线，并且已经安装 KXBuild。第一次走完大约一小时，大部分时间花在下载依赖上。
本地构建和 EAS Build 怎么选 {#eas-or-local}
EAS Build 在 Expo 的云端 macOS 上构建，不用自己维护构建环境，证书也可以交给 EAS 管理。代价是免费账户每月的构建次数有限，高峰期要排队，每次改完原生配置都要等一轮云端构建。eas build --local可以在本机构建，但 iOS 端仍然要求 macOS 和 Xcode。
在 Windows 上用 KXBuild 本地构建，不排队、不占云端次数，还能对原生代码下断点。需要你自己准备证书和描述文件，ios 目录也在本机生成。两种方式可以并存，团队里有人用 EAS 出正式包、有人在 Windows 上本地调试，互不影响。
新建 Expo 工程 {#create}
已有工程在 VS Code 中「文件 → 打开文件夹」打开工程根目录即可，跳到下一节。
没有现成工程的，用 Expo 官方命令新建。工程的父目录用短路径，node_modules 层级很深，放得太深在 Windows 上容易遇到路径过长的错误。
cd D:\work npx create-expo-app@latest expohello新建完成后在 VS Code 中打开D:\work\expohello。
也可以直接用 KXBuild 的模板新建，以下两种做法任选其一。
- VS Code 插件。命令面板运行
KXBuild: 新建项目，模板选「Expo 应用」。 - 命令行。执行
kxbuild project create -t expo_app -n expohello -o D:\work。
模板的说明见项目模板。
在 app.json 里填好 iOS 配置 {#app-json}
Expo 工程的 ios 目录是按 app.json 生成的，所以在生成之前先把 iOS 相关的字段填好，能省掉一次重新生成。下面只列出和 iOS 相关的字段，其他字段保持原样。
{"expo":{"name":"expohello","version":"1.0.0","ios":{"bundleIdentifier":"com.example.expohello","buildNumber":"1","appleTeamId":"ABCDE12345","infoPlist":{"NSCameraUsageDescription":"用于扫描二维码","NSMicrophoneUsageDescription":"用于录制视频中的声音"}}}}各字段的作用如下。
| 字段 | 作用 |
|---|---|
version | 商店里显示的版本号，对应 CFBundleShortVersionString |
ios.buildNumber | 构建号，对应 CFBundleVersion，每次上传 App Store Connect 都要比上一次大 |
ios.bundleIdentifier | Bundle ID，要和开发者后台注册的 App ID、描述文件一致 |
ios.appleTeamId | 开发者账号的 Team ID，在 developer.apple.com 的 Membership 页能看到 |
ios.infoPlist | 直接写进 Info.plist 的键，权限说明文字放在这里 |
用到相机、麦克风、相册、定位的 App 必须写对应的权限说明，缺了会在调用时直接闪退，审核也会被拒。有些 Expo 库（例如 expo-camera）支持在plugins里配置权限文字，按该库文档写即可，效果相同。
签名需要的 .p12 证书和 .mobileprovision 描述文件放进证书目录，开发阶段用 Apple Development 证书和包含这部 iPhone UDID 的 Development 描述文件，获取和放置方法见证书与签名。
体检并安装原生依赖 {#doctor}
第一次打开工程必须先体检。它会检查 Expo 环境，并生成、准备好 iOS 端的工程，完成后工程下多出 ios 目录。以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
- 命令行。执行下面的命令。
kxbuild doctor D:\work\expohello体检之后进入 ios 目录安装原生依赖。第一次会下载较多内容，时间取决于网络。
cd D:\work\expohello\ios pod install完成后 ios 目录下会有expohello.xcworkspace，之后构建都用它。CocoaPods 的更多用法见 CocoaPods。
在 iPhone 上运行开发版 {#run}
先用数据线连上 iPhone，解锁后点「信任此电脑」，并在「设置 → 隐私与安全性 → 开发者模式」中打开开发者模式，手机会重启一次。驱动和手机设置见设备准备。
开发版的 JS 从电脑上的 Metro 加载，所以先另开一个终端，在工程根目录启动 Metro。
cd D:\work\expohello npx expostart然后在 KXBuild 视图中选中这台 iPhone，按 F5。KXBuild 会依次构建、签名、安装、启动 App 并附加调试器。第一次调试某个 iOS 版本时会自动下载对应的符号库，有几个 GB，只需一次。
App 启动后，改 JS 或 TypeScript 代码保存即可自动刷新，不用重新构建。两种代码各用各的调试器。
- 原生代码（ios 目录下的 Swift、Objective-C）在 VS Code 中下断点，F5 启动后直接生效，用法见运行与调试。
- JS 代码在运行
npx expo start的终端按j打开 Expo 的调试器，在里面下断点。
App 一打开就红屏，通常是手机连不上电脑上的 Metro。确认手机和电脑在同一个局域网，Windows 防火墙放行 Node.js 或 Metro 的 8081 端口。
改了原生代码要先停止调试再按 F5，调试工具栏上的「重启」不会重新编译。
修改 app.json 之后重新生成 iOS 工程 {#regenerate}
改了 Bundle ID、版本号、权限说明、图标，或者新装了带原生代码的库，都要重新生成 ios 目录，否则改动不会进入 App。体检只在 ios 目录不存在时生成它，所以要先删掉旧的 ios 目录再体检。
cd D:\work\expohelloRemove-Item-Recurse-Force.\ios kxbuild doctor D:\work\expohello cd ios pod install插件用户删掉 ios 目录后在 KXBuild 视图运行「体检并修复开发环境」，再到 ios 目录执行pod install，效果相同。
重新生成会覆盖 ios 目录下的所有手动修改。需要长期保留的原生配置写进 app.json 或 config plugin，这是 Expo 推荐的做法。如果你的工程已经把 ios 目录纳入版本管理、直接改原生文件，就不要删目录，改用 属性列表编辑器和工程设置编辑器直接修改。
打出 Release ipa {#release}
上架前先确认两件事。ios.buildNumber比上一次上传的大，改过就按上一节重新生成。证书目录里有 Apple Distribution 证书和 App Store 类型的描述文件，用 Development 描述文件签的包上传时会被拒。
Release 构建会把 JS 打包进 App，运行时不再依赖 Metro。以下两种做法任选其一。
- VS Code 插件。在 KXBuild 视图的「构建配置」节点切到 Release，命令面板运行
KXBuild: 构建。 - 命令行。在工程根目录执行下面的命令。
kxbuild build.\ios\expohello.xcworkspace-c Release工程的 Release 配置没有指定发布证书时，命令行加-D CODE_SIGN_IDENTITY="Apple Distribution"临时覆盖。
构建完成后得到ios\build\expohello.ipa，结构和 Xcode 导出的一样。在 Windows 上用 Appuploader 上传到 App Store Connect，处理完成后出现在 TestFlight 页，先发给测试员验证再提交审核，详见发布与上架。
常见问题 {#faq}
体检没有生成 ios 目录。带-v再运行一次kxbuild doctor D:\work\expohello -v，输出里会写明失败的步骤，多数是依赖没装完或网络中断。
编译报找不到 Pods 里的头文件或模块。确认已经在 ios 目录执行过pod install，并且构建的是.xcworkspace而不是.xcodeproj。
报文件名过长或找不到文件。把工程移到D:\work这类短路径下，删掉 ios 目录重新生成。
安装后启动就退出，提示 didn’t start in time。App 很可能启动即崩溃，常见原因是缺少权限说明或原生库没有重新生成。查看设备日志和崩溃报告的方法见运行与调试和排错与 FAQ
更多信息可以查看官网教程：https://www.kxbuild.net/zh
