刚接触 React Native 的人，很容易被“装好依赖就能跑”这句话误导。实际上，你能从 npm 上拉下来的 react-native 版本有很多，但真正能在你的电脑上编译通过的版本，往往就那么几个。这个“可编译的可拉取版本范围”，是由 Node.js 版本、JDK 版本、Android Gradle Plugin 版本、Xcode 版本和 CocoaPods 版本共同围出来的一条狭窄通道。如果你不了解这条通道的边界，项目启动时会连续撞墙，报错一个接一个，而且每个报错看起来都像环境问题，其实根子都在版本上。这篇文章就围绕版本范围怎么确定、怎么拉取、怎么启动展开，适合那些被 RN 编译问题折磨过，或者正准备从零搭一个 RN 项目的开发者。
1. 先搞清楚：可编译版本范围到底由什么决定
1.1 npm 上的版本清单只是“可拉取范围”
打开终端执行npm view react-native versions --json，你会看到一份长得吓人的版本列表，从早期的 0.1 到现在的 0.77，整整几百个版本。这个列表就是“可拉取范围”——只要你网络正常，npm 不会拦着你把任何一个版本下载到本地。
但“能下载”和“能编译”完全是两回事。打个比方：超市里摆着的食材你都能买回家，但能不能做出一顿饭，取决于你家有没有对应的锅、灶和调味料。RN 版本也一样，每个版本发布时都带着自己的一套工具链要求，写在package.json的engines字段、peerDependencies字段以及官方模板的build.gradle和Podfile里。这些才是“可编译”的第一道门槛。
我之前见过一个团队，直接拉了一个当时最新的 RC 版本，npm install很顺利，结果run-android编译到一半报错，提示需要 JDK 17，而团队电脑上装的是 JDK 11。整组人卡了大半天，最后换了稳定版才解决。这就是典型的“只看了可拉取范围，没看可编译范围”。
1.2 真正的边界由本地工具链决定
每个 RN 版本在发布时，基本都会对应一套固定的构建工具版本。以 Android 端为例，模板里的android/gradle/wrapper/gradle-wrapper.properties会指定 Gradle 版本，android/build.gradle会指定 Android Gradle Plugin（AGP）版本，这两个版本又反过来决定你需要哪个 JDK。
这里我结合官方模板和实际项目经验，整理了一份常见版本对应关系，注意它不是绝对真理，但可以帮你快速定位问题：
| React Native 版本 | React 版本 | JDK | Gradle | AGP | compileSdk |
|---|---|---|---|---|---|
| 0.71.0 | 18.2.0 | 11 | 7.6.1 | 7.4.1 | 33 |
| 0.72.0 | 18.2.0 | 17 | 8.0.2 | 8.0.2 | 33 |
| 0.73.0 | 18.2.0 | 17 | 8.3 | 8.1.1 | 34 |
| 0.74.0 | 18.2.0 | 17 | 8.6 | 8.2.1 | 34 |
iOS 端也有类似限制。0.73 之后，官方模板要求相对现代的 Xcode 和 CocoaPods 版本，CocoaPods 最好在 1.12 以上。如果你还在用老版本 Xcode，pod install阶段就会遇到各种 React-Core 的 podspec 兼容问题。
所以判断“某个 RN 版本能不能编译”，不要只看版本号数字，而要顺着这条链去对：RN 版本对应的 AGP/Gradle 版本，你的 JDK 和 Android SDK 是否满足。链路上任何一环对不上，编译就会炸。
1.3 官方兼容版本矩阵在哪里查
很多初学者喜欢在网上问“0.73 需要哪个版本 JDK”，其实答案就在发布说明里。RN 的 GitHub Release 页面会写清楚每个版本的最低要求，同时项目初始化之后，本地模板文件里也藏着完整答案。
实操中我一般看三个地方：
node_modules/react-native/package.json：看engines和peerDependencies，确定 Node 和 React 版本要求。node_modules/react-native/template/android/build.gradle：看 AGP 版本。node_modules/react-native/template/gradle/wrapper/gradle-wrapper.properties：看 Gradle 发行版本。
这个方法比网上搜到的二手信息可靠得多，因为每个版本之间差异明显，你直接在本地查到的就是当前项目实际使用的版本，不会出现“网上说用 JDK 11，但模板里却写着 JDK 17”的冲突。养成这个习惯之后，版本问题基本能把排查范围缩小一半。
2. 拉取指定版本：查询版本库和锁定版本的具体操作
2.1 用 npm 一次性摸清所有可拉取版本
拉取版本的第一步，是先知道有哪些版本可选、哪些才是稳定版。这里我常用的有这几条命令：
# 查看所有可用版本，列表会很长 npm view react-native versions --json # 只查看最新几个稳定版本 npm view react-native versions --json | tail -n 30 # 查看 npm 上的标签 npm view react-native dist-tags --json # 查看某个具体版本的依赖要求 npm view react-native@0.73.6 peerDependencies engines --jsondist-tags的输出类似这样：
{ "latest": "0.77.1", "next": "0.78.0-rc.2", "beta": "0.78.0-rc.2", "old": "0.69.12" }这里的latest是 npm 默认拉取的版本，但它不代表所有场景下最合适的版本。next和beta是发布候选版本，可以用来提前体验新特性，但不建议作为正式项目基线，因为第三方库大概率还没跟上。
版本号里的 0.x.y 有个规律：x 是里程碑版本，y 是补丁版本。一般同一里程碑下，优先选择补丁版本最高的，比如 0.73.6。补丁版本往往只修 bug，不会引入破坏性变化，风险最低。
2.2 锁定版本初始化的三种方式
确定了要用的版本之后，初始化项目时一定要把版本钉死，否则很容易出现“日志里写着 0.73.6，实际拉下来却是 0.77.1”的灵异事件。推荐三种方式：
第一种，直接用 CLI 指定版本：
npx react-native@0.73.6 init MyApp --version 0.73.6注意npx react-native@0.73.6和--version 0.73.6要保持一致。前者指定的是 CLI 工具本身版本，后者指定的是项目模板版本。如果忽略--version，CLI 会按照它的默认偏好去选模板版本，不一定是你想要的那个。
第二种，手动创建package.json后安装依赖：
{ "name": "MyApp", "version": "0.0.1", "private": true, "scripts": { "android": "react-native run-android", "ios": "react-native run-ios", "start": "react-native start" }, "dependencies": { "react": "18.2.0", "react-native": "0.73.6" } }然后执行npm install。这种方式适合在已有工程上手动切版本，但需要你把android和ios原生目录也准备好，对新手略麻烦。
第三种，从 GitHub 模板仓库拉取指定 tag。适合想深度定制模板的团队，但不推荐日常使用，因为上手成本高，而且容易遗漏配置。
初始化完成后，一定要做一次校验，打开package.json确认版本，再执行npx react-native config看项目配置是否完整。这一步能提前发现很多半途而废的安装问题。
2.3 版本拉取时的源与缓存坑
在国内网络环境下拉 RN，很多团队会配置 npmmirror 镜像源。这个思路没错，但坑也不少。镜像源虽然同步频繁，但在某些二进制依赖上可能有延迟，导致npm install时下载失败。
我一般会在项目根目录放一个.npmrc：
registry=https://registry.npmmirror.com fetch-retries=3 fetch-retry-factor=2 network-timeout=600000network-timeout尤其重要，RN 依赖体积大，下载慢是常态，默认超时时间容易直接中断安装。另外，如果之前用官方源生成过package-lock.json，切到镜像源后可能因为resolved字段指向原源而导致安装校验失败。解决办法是删掉锁文件重新安装，或者从一开始就统一 registry。
npm cache clean --force这个命令我很少用，它只是强制清理缓存，并不能解决依赖错乱。遇到疑似坏缓存时，优先用npm install --prefer-online，让 npm 尽量从远端拉取，而不是复用本地缓存，这样更稳。
3. 操作启动：从拉取到跑起来的完整动作
3.1 启动 Metro 之前的环境体检
不要一上来就执行run-android。我见过太多人卡在环境变量上，报错信息千奇百怪，但归根结底就是环境没配好。RN 官方其实提供了一个很好的诊断工具：
npx react-native info这条命令会输出当前操作系统的版本、CPU、内存、Node、Yarn、npm、Watchman、Xcode、Android SDK、JDK 等环境信息。根据输出，你可以对照打算使用的 RN 版本要求，快速确认本地环境是否在“可编译范围”内。
尤其是 Watchman，这个工具经常被忽略。在 macOS 和 Linux 上，Metro 依赖 Watchman 来监听文件变化。没有 Watchman 的话，文件变更可能不会被及时感知，表现为改完代码页面不刷新、甚至直接报EMFILE: too many open files。安装 Watchman 之后，可以在项目目录执行一句：
watchman watch-project .另外，Android 调试离不开 ADB。执行adb devices确认设备能被识别，这是后续所有 Android 启动操作的前提。ADB 最常被用来做端口转发、安装调试包、查看日志，后面启动真机调试也要用到。
3.2 Metro 启动与连接设备
启动打包器的标准命令是：
react-native start或者用 npx：
npx react-native start首次启动或者依赖有变化时，我习惯带参数：
npx react-native start --reset-cache--reset-cache会清掉 Metro 的缓存，让打包器重新读取文件。它能解决很多“明明改了代码，但界面死活没变化”的诡异问题，但代价是首次打包会慢一点，所以不要每次都加。
Metro 默认监听 8081 端口。如果你启动时看到Error: listen EADDRINUSE :8081，说明端口被占了。先用下面的命令查一下：
lsof -i :8081 -P -n然后杀掉对应进程即可。Android 模拟器可以直接通过localhost:8081访问宿主机上的 Metro，但 Android 真机不一样，它访问的localhost是自己的回环地址，所以需要执行一次端口转发：
adb reverse tcp:8081 tcp:8081这条命令把手机上的 8081 端口转发到电脑的 8081 端口，这样真机就能加载到 Metro 提供的 JS bundle。iOS 模拟器不用做这种操作，因为模拟器直接共享宿主机的网络环境。iOS 真机则需要让 Metro 监听局域网 IP，并在手机的 Dev Settings 里配置 Debug server host。
3.3 编译启动 App 的完整链路
Android 端编译启动的入口是：
npx react-native run-android这个命令会检查设备或模拟器，如果没检测到，它会提示你先打开一个模拟器，或者连接一台 USB 调试的真机。检测到设备后，它会调用 Gradle 编译并安装 debug APK。编译过程会经历:app:assembleDebug，耗时长短取决于你的 CPU、内存和依赖体积。
Android 编译最常出问题的就是 JDK 版本和 SDK 目录。执行前，我建议先确认几个环境变量：
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 export ANDROID_HOME=$HOME/Android/Sdk export PATH=$PATH:$ANDROID_HOME/platform-tools如果你用的 RN 版本需要 compileSdk 34，那 Android SDK 里必须装platforms;android-34和对应的 Build-Tools。缺少这些，Gradle 会直接报错，而且报错信息很直白，照着补就行了。
iOS 端编译启动的入口是：
cd ios pod install cd .. npx react-native run-ios --simulator "iPhone 15"pod install会根据Podfile.lock拉取 React-Core 等原生依赖，这一步在国内网络环境下同样可能很慢。如果公司电脑的 Ruby 版本太老，建议用rbenv管理 Ruby 版本，避免 CocoaPods 莫名其妙报错。
第一次编译启动成功后，还需要知道怎么打开调试菜单。Android 上是执行adb shell input keyevent 82，或者摇一摇手机；iOS 模拟器上是Command + D（新版是Ctrl + Command + Z）。在调试菜单里可以 Reload、打开 DevTools、切换 Debugger，这些是日常开发必不可少的手感操作。
4. 常见启动失败与问题排查实录
4.1 “版本不在可控范围”的典型报错与处理
启动 RN 项目时，很多报错其实都是在提醒你“版本范围没对上”。我把遇到频率最高的几个整理成了表格，方便你对照排查。
| 报错信息 | 常见原因 | 处理方式 |
|---|---|---|
| React Native version mismatch | 原生端与 JS 端版本不一致，常见于升级或切换分支后未重新构建 | 清掉android/build、ios/build，执行pod install，重新从头编译 |
| TypeError: Cannot read property 'newArchEnabled' of null | 老工程被新 CLI 读取时，配置里缺少对应字段 | 检查react-native.config.js，或重新生成工程并迁移改动 |
| Could not find com.facebook.react:react-android:x.x.x | Gradle 仓库中没有对应 RN 原生依赖 | 在android/build.gradle中加入mavenCentral()仓库，或检查是否被镜像源屏蔽 |
| SDK location not found. Define a valid SDK location | ANDROID_HOME没配置或配置错误 | 设置ANDROID_HOME，并在android/local.properties中写入sdk.dir |
这些报错有一个共同点：它们的根源都不是业务代码，而是版本范围判断失误。所以遇到它们，先不要乱改代码，而是回到版本匹配上找原因。
4.2 启动过程中 Metro、ADB 与 CocoaPods 的坑
Metro 启动阶段最常见的坑是文件监听溢出和端口冲突。除了之前说的EMFILE问题，还有一种是 Metro 启动后一直转圈，终端没有日志。这时候先看端口是否真的被监听，然后确认手机和电脑之间的连接。Android 真机如果执行了adb reverse还是加载不到 bundle，检查一下手机上的 Dev Settings 是否被人为指定成了某个 IP，如果有，清掉再试。
iOS 端常见的坑集中在 CocoaPods。比如：
[!] Unable to find a specification for `React-Core`这通常是因为Podfile里node_modules/react-native的路径不对，或者node_modules不完整。解决办法是删除Pods、Podfile.lock，再执行pod install --repo-update。注意--repo-update会更新本地 CocoaPods 仓库，能解决部分依赖源问题，但耗时较长。
还有一个容易踩的坑：Android 运行时报Unable to load script from assets index.android.bundle。这是 debug 包找不到 JS bundle 的经典报错。正常情况下 debug 包会通过 Metro 加载 bundle，但如果 Metro 没启动，或者端口不通，就会出现这个错误。临时解决办法是手动生成一个 bundle 塞进 assets 目录，但这不是长久之计，根治还是要保证 Metro 能正常访问。
4.3 依赖版本错乱后的“一键重置”流程
如果项目被折腾得乱七八糟，别急着一行一行改依赖，我一般按下面的顺序整体重置：
- 停止 Metro，关闭模拟器。
- 执行
watchman watch-del-all，清掉文件监听状态。 - 删除
node_modules、ios/Pods、ios/Podfile.lock、android/.gradle、android/build、ios/build。 - 重新执行
npm install，最好用npm ci，它会严格基于锁文件安装。 - 在 iOS 目录里执行
pod install --repo-update。 - 最后再执行
npx react-native run-android或npx react-native run-ios。
这个流程是最后手段，不要一遇到问题就盲目重置。好的排查习惯是先看完整日志，定位到具体报错，再决定要不要重置。因为重置一次的成本很高，尤其是 iOS 的 pod 重新安装，能占用你半个下午。
5. 版本选择与启动的最佳实践
5.1 我会怎么选“可编译版本”
踩过几次坑之后，我给自己定了一条规矩：新项目不直接拉latest，而是选择latest前一到两个 minor 版本的最新 patch。原因很现实：RN 社区里，第三方原生库的适配速度通常要滞后几个版本。你用了最新版，装一个刚更新的原生库，很可能就遇到 “SDK 版本不匹配” 或 “New Architecture 不兼容”。
每次选版本前，我会跑一遍npx react-native info，看看本地环境的实际版本，然后反向选择 RN 版本。比如本地 JDK 是 17，Android SDK 里已经装了 compileSdk 34，我就会选 0.73 或者 0.74 系列，而不是卡在需要 JDK 11 的 0.71 上。
有一次我在老项目里从 0.70 升级到 0.72，没仔细看模板里的 Gradle 版本，结果编译时提示需要 JDK 17。我切了 JDK 17 之后，又因为 Gradle 版本跟 Android Studio 里内置的 Gradle 不一致，折腾了好一阵。那次之后我就记住了：任何升级操作之前，先把模板里的build.gradle和gradle-wrapper.properties打开看一遍，确认工具链要求全部满足再动手。
5.2 可以直接抄的一套启动配置示例
最后放一套我目前在用的最小启动配置，供你参考。首先是.npmrc：
registry=https://registry.npmmirror.com fetch-retries=3 network-timeout=600000然后是package.json里的关键依赖和脚本：
{ "dependencies": { "react": "18.2.0", "react-native": "0.73.6" }, "devDependencies": { "@babel/core": "^7.24.0", "@babel/preset-env": "^7.24.0", "@babel/runtime": "^7.24.0", "@react-native/babel-preset": "0.73.6", "@react-native/metro-config": "0.73.6", "@react-native/typescript-config": "0.73.6", "typescript": "5.0.4" }, "scripts": { "start": "react-native start --reset-cache", "android": "react-native run-android", "ios": "cd ios && pod install && cd .. && react-native run-ios --simulator \"iPhone 15\"" } }环境变量我一般放在~/.zshrc或~/.bashrc里：
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 export ANDROID_HOME=$HOME/Android/Sdk export PATH=$PATH:$ANDROID_HOME/platform-tools export PATH=$PATH:$ANDROID_HOME/emulator这里要注意，示例里的start脚本带了--reset-cache，它只适合初始化后第一次启动。日常开发时不建议每次都用，否则 Metro 缓存一直清，打包速度会越来越慢。
如果你现在正被 RN 启动问题折磨，我建议你先别急着重装，先跑npx react-native info和npm view react-native@对应版本 engines，把版本范围确认清楚再动手。可拉取的版本永远比可编译的多，真正能让你顺利跑起来的版本，永远只占冰山一角。把版本这件事拿捏住，项目启动就会顺畅很多。
