跳到主要内容
教程目录

React Native 在 Windows 上开发 iOS App，从新建到真机运行

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

新建项目

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

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

用 React Native 社区 CLI 新建

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

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

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

用 KXBuild 的模板新建

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

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

体检

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

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

安装 pods

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

1cd D:\work\RnHello\ios
2pod install

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

改 Bundle ID

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

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

工程设置编辑器的 General 页

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

连接 iPhone

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

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

更多情况见设备准备。

启动 Metro

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

1npx react-native start

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

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

真机运行与 Fast Refresh

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。

调试原生代码

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

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

VS Code 中 Windows 上真机调试 iOS App

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

改 App 名称和图标

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

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

现有脚本里的 xcodebuild 照常可用

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

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

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

打包 Release ipa

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

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

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

  • VS Code 插件。在 KXBuild 视图的「构建配置」节点切到 Release，命令面板运行 KXBuild: 构建。
  • 命令行。在项目根目录运行下面的命令。
1kxbuild build .\ios\RnHello.xcworkspace -c Release

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

常见问题

App 一打开就红屏，提示连不上开发服务器

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

编译报找不到 React 头文件或某个 Pod

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

编译在 Run Script 阶段报错

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

提示文件名过长或找不到文件

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

其他错误见排错与 FAQ。