这篇带你在 Windows 上从零新建一个 React Native 项目，装到 iPhone 上边改边看效果，再打出可以上架的 ipa。适合用 Windows 写 RN、之前只能跑 Android 端的开发者。你需要准备 Apple 开发者账号、一台 iPhone 和数据线，电脑和手机连同一个局域网，并且已经安装 KXBuild。用 Expo 的项目流程略有不同，见 Expo 技术栈页。安装地址：https://www.kxbuild.net/zh

新建项目 {#create}

已有项目在 VS Code 中「文件 → 打开文件夹」打开项目根目录（package.json 所在的目录），或者把项目目录拖进 VS Code 即可。没有现成项目的，按下面的方式新建。

项目放在短路径下，例如 D:\work。 RN 项目的依赖目录很深，放得太深在 Windows 上容易遇到路径过长的错误。

用 React Native 社区 CLI 新建 {#create-cli}

React Native 官方文档里不使用框架时的新建命令如下，项目名只用字母和数字。

cd D:\work
npx @react-native-community/cli@latest init RnHello

CLI 会生成 RnHello 目录并安装 JS 依赖，ios 子目录里是 iOS 端的 Xcode 工程。在 Windows 上它会跳过 CocoaPods 这一步，后面我们自己装。

用 KXBuild 的模板新建 {#create-template}

模板会自动完成依赖安装和 pod install。以下两种做法任选其一。

• VS Code 插件。命令面板运行 KXBuild: 新建项目，模板选「React Native 应用」。
• 命令行。运行 kxbuild project create -t react_native_app -n RnHello -o D:\work。

体检 {#doctor}

第一次打开项目必须先做这一步。 它会检查 React Native 环境，并准备好 iOS 端的工程。以下两种做法任选其一。

• VS Code 插件。在 KXBuild 视图标题栏「···」中运行「体检并修复开发环境」。
• 命令行。运行下面的命令。

kxbuild doctor D:\work\RnHello

安装 pods {#pod-install}

RN 的 iOS 端依赖都通过 CocoaPods 安装。体检不会替你执行 pod install，用社区 CLI 新建或从仓库拉下来的项目，体检之后要在 ios 目录运行一次。

cd D:\work\RnHello\ios
pod install

完成后 ios 目录下会出现 RnHello.xcworkspace，之后构建都用它，不要再用 RnHello.xcodeproj。每次新增或升级带原生代码的 npm 包之后，都要重新 pod install。更多用法见 CocoaPods。

改 Bundle ID {#bundle-id}

社区 CLI 生成的 Bundle ID 是 org.reactjs.native.example 开头的示例值，装机前改成你自己的，并在 Apple 开发者后台注册同名的 App ID。

在 KXBuild 视图里右键 RnHello 这个 target，选择「KXBuild: 编辑目标设置」，在 General 页的 Bundle Identifier 里修改。同一页的 Signing 分组可以选择团队和签名方式，详见工程设置编辑器。

真机运行还要把 Apple Development 证书和包含这台 iPhone 的描述文件放进证书目录，见证书与签名。

连接 iPhone {#device}

用数据线连上 iPhone，第一次按下面的顺序做一遍。

1. KXBuild 视图的设备节点提示「点击配置」时点一下，安装 Apple 设备驱动。
2. 手机解锁，在弹窗里点「信任此电脑」。
3. 手机上打开「设置 → 隐私与安全性 → 开发者模式」，手机会重启一次。
4. 在 KXBuild 视图的「设备」节点下点一下这台 iPhone，选为当前设备。

更多情况见设备准备。

启动 Metro {#metro}

Debug 包里没有 JS 代码，App 启动后通过局域网从电脑上的 Metro 开发服务器加载。在 VS Code 里另开一个终端，在项目根目录运行下面的命令，保持它一直开着。

npx react-native start

手机要能连到电脑的 8081 端口，第一次在 Windows 上用 RN 调 iPhone 时注意下面三点。

• 手机和电脑连同一个 Wi-Fi 或同一个局域网，访客网络和开了客户端隔离的网络连不通。
• Windows 防火墙放行 8081 端口的入站连接。用管理员身份打开 PowerShell 执行下面这条命令即可。
• App 第一次启动时，iOS 会弹窗询问是否允许查找本地网络上的设备，点「允许」。点错了可以删掉 App 重新安装，弹窗会再出现。

New-NetFirewallRule -DisplayName "Metro 8081" -Direction Inbound -Protocol TCP -LocalPort 8081 -Action Allow

真机运行与 Fast Refresh {#run}

Metro 起来后，在 KXBuild 视图中选中 iPhone，按 F5。KXBuild 会构建、签名、安装、启动 App，并接上原生调试器。第一次构建要编译全部 pods，耗时比之后长。第一次调试某个 iOS 版本时还会自动下载符号库，有几个 GB，只需要一次。

App 打开后看到欢迎页，就说明 JS 已经从 Metro 加载成功。之后的日常开发是这样的。

• 在 VS Code 里改 App.tsx 并保存，Fast Refresh 会立刻把改动推到手机上，组件状态保留。
• 摇一摇手机打开开发者菜单，可以手动刷新或关闭 Fast Refresh。
• JS 断点用 React Native 自带的调试工具。在运行 Metro 的终端里按 j，会打开 React Native DevTools，在里面的 Sources 面板打断点。

改了不同的东西，要做的事不一样。

改了什么	要做什么
JS、TS、样式、图片	保存即可，Fast Refresh 自动更新
装了纯 JS 的 npm 包	重启 Metro 后在手机上刷新
装了带原生代码的 npm 包	ios 目录重新 pod install，停止调试后按 F5
ios 目录下的原生代码、Info.plist	停止调试后按 F5

调试工具栏上的「重启」不会重新编译，改了原生部分一定要停止后重新按 F5。

调试原生代码 {#native-debug}

写原生模块、排查启动崩溃时，需要在 Swift 或 Objective-C 代码里断点。在 ios\RnHello\AppDelegate.swift 或你自己写的原生模块里打断点，按 F5 启动后就会停在那里。变量、调用栈、监视和调试控制台都是 VS Code 标准的调试视图，调试控制台里还能直接输入 lldb 命令。

原生断点和 JS 断点互不影响，可以同时用。

App 的输出在「输出 → KXBuild Console」，构建日志在「输出 → KXBuild」。更多调试方式见运行与调试。

改 App 名称和图标 {#name-and-icon}

主屏幕上显示的名字是 ios\RnHello\Info.plist 里的 CFBundleDisplayName，在 VS Code 里双击这个文件，用属性列表编辑器直接改值即可。

iOS 图标在 ios\RnHello\Images.xcassets 的 AppIcon 里，新建的项目这里是空的。在资源管理器中右键 Images.xcassets，选择「KXBuild: 打开资源目录」，选中 AppIcon 后用「用一张 1024×1024 图生成全部尺寸…」选一张不小于 1024 的正方形 PNG，所有尺寸一次生成。上架前点标题栏的「KXBuild: 编译检查资源目录」，缺少的尺寸会列在「问题」面板里，详见资源目录编辑。

现有脚本里的 xcodebuild 照常可用 {#xcodebuild}

安装 KXBuild 后，Windows 上也有和 macOS 同名的 xcodebuild、xcrun 命令。项目里已有的构建脚本、CI 脚本里调用 xcodebuild 的地方不用改，例如下面这条在 Windows 上也能直接跑。

xcodebuild -workspace ios\RnHello.xcworkspace -scheme RnHello -configuration Debug -sdk iphoneos

兼容的是常用参数。xcodebuild test 和 -exportArchive 不支持，要出上架用的 ipa 改用下一节的 kxbuild build。支持的参数列表见 xcodebuild / xcrun 兼容。

打包 Release ipa {#release}

Release 构建会把 JS 打包成 bundle 放进 App，装上后不再需要 Metro，可以直接给别人用和上架。

先把版本号调大。在工程设置编辑器的 General 页修改 Marketing Version（商店里显示的版本）和 Current Project Version（构建号），每次上传 App Store Connect 构建号都要比上一次大。证书目录里要有 Apple Distribution 证书和 App Store 类型的描述文件。

然后用 Release 配置构建，以下两种做法任选其一。

• VS Code 插件。在 KXBuild 视图的「构建配置」节点切到 Release，命令面板运行 KXBuild: 构建。
• 命令行。在项目根目录运行下面的命令。

kxbuild build .\ios\RnHello.xcworkspace -c Release

构建完成后 ios\build\RnHello.ipa 就是可以上传的包。在 App Store Connect 里新建好 App，在 Windows 上用 Appuploader 上传这个 ipa，处理完成后先在 TestFlight 里装到手机上验证，再提交审核。完整步骤见发布与上架。

常见问题 {#faq}

App 一打开就红屏，提示连不上开发服务器 {#faq-red-screen}

手机连不上电脑上的 Metro，是网络问题。按顺序检查 Metro 是否还在运行、手机和电脑是否在同一网络、防火墙是否放行了 8081、手机上是否允许了本地网络权限。本地网络权限可以在手机「设置 → 隐私与安全性 → 本地网络」里找到这个 App 打开。

编译报找不到 React 头文件或某个 Pod {#faq-pods}

没有 pod install，或者构建的是 .xcodeproj。在 ios 目录运行 pod install，之后构建 .xcworkspace。

编译在 Run Script 阶段报错 {#faq-run-script}

RN 环境没准备好，常见于刚从仓库拉下项目或刚升级 RN 版本。带上项目路径重新运行体检。

提示文件名过长或找不到文件 {#faq-long-path}

项目放得太深。把项目挪到 D:\work 这样的短路径下，重新 pod install。体检也会开启 Windows 的长路径支持，过程中要确认一次管理员权限。

其他错误见排错与 FAQ。