放弃图形化安装器：纯命令行搭建React Native安卓开发环境实战

1. 为什么我要放弃图形化安装器，改用纯命令行搭 RN 安卓环境

很多人第一次接触 React Native 的安卓开发环境，都是被各种"一键安装包""集成安装器"带进门的。点几下鼠标，等进度条走完，看起来环境就搭好了。但真正开始跑项目的时候，问题就来了：react-native run-android 报错说找不到 SDK 路径，Gradle 下载卡在某个依赖上不动，模拟器启动了但应用装不上去，启动之后一片白屏。你去翻安装器生成的配置文件，发现它把 SDK 装到了一个带空格的目录里，或者环境变量只写了一半，你根本不知道它到底改了什么。

这就是所谓的"黑盒"。安装器帮你做了决策，但没告诉你决策是什么，出了问题你连排查的入口都找不到。而"臃肿"则是另一个极端：为了兼容所有可能的场景，安装器会把 Android Studio、多个版本的 SDK Build-Tools、多个系统镜像、模拟器全套都塞进你的硬盘，动辄占用几十个 GB，而你可能只需要其中很小一部分。

所以这篇文章要聊的，是在 Windows 上完全用命令行把 React Native 的安卓开发环境搭起来。核心思路很简单：每一个组件都手动下载、手动配置、手动验证，你清楚地知道 JDK 装在哪、SDK 装在哪、环境变量指向哪里、Gradle 用的是哪个版本。这样做的直接好处是，当构建失败时，你能顺着命令行报错一路定位到具体环节，而不是对着一个图形界面发呆。

这套方案适合几类人：一是硬盘空间紧张、不想装完整 Android Studio 的开发者；二是已经在用 VS Code 或其它轻量编辑器写 RN 代码，只缺安卓构建链路的人；三是被各种"环境搭建教程"坑过、想彻底搞明白这套工具链到底怎么串起来的人。如果你只是想快速跑个 Demo 且完全不关心底层，那装个 Android Studio 也无可厚非，但只要你打算长期做 RN 开发，命令行方案迟早要掌握。

下面我会按照真实的搭建顺序，从 JDK 开始，一路讲到能成功跑起一个 RN 项目，中间穿插我踩过的坑和验证方法。整个过程不需要打开任何图形化安装向导，全部在 PowerShell 或 CMD 里完成。

2. 搭建前的全局规划：目录、版本与依赖关系

2.1 先想清楚目录结构，别让空格和中文毁掉一切

命令行搭建最容易翻车的地方，不是命令写错，而是路径里带了空格或中文。Windows 默认的用户目录是 C:\Users\你的名字，如果名字是中文，或者你习惯把工具装在 Program Files 下，后面 Gradle、SDK 工具链里某些脚本解析路径时就会出问题。这类报错往往很隐晦，比如某个 .bat 脚本执行到一半突然退出，或者提示"系统找不到指定的路径"，你盯着命令看半天也看不出哪里错了。

我的建议是，在盘符根目录下建一个纯英文、无空格的工具目录，比如 D:\dev，然后所有东西都往里放：

这个结构不是随便定的。android-sdk 作为 SDK 根目录，下面各个子目录是 Android SDK 约定的标准布局，sdkmanager 和 avdmanager 这些工具会默认往这些位置找东西。你手动指定 ANDROID_HOME 指向 D:\dev\android-sdk，后续所有工具就都能对上号。

注意：如果你之前的用户名是中文，且不想重装系统，最省事的办法就是新建一个纯英文的本地账户，或者干脆把所有开发工具都放到 D:\dev 这种与用户目录无关的位置。环境变量也尽量用系统级而非用户级，避免不同账户之间互相干扰。

2.2 版本选择：JDK、SDK、Gradle 三者的兼容关系

React Native 对 JDK 版本是有要求的。较新的 RN 版本（0.73 及以上）推荐 JDK 17，而更早的版本可能还在用 JDK 11。这里有个常见的误区：很多人以为 JDK 版本越高越好，直接上 JDK 21，结果 Gradle 构建时报一堆"不支持的类文件版本"。原因是 Gradle 本身对 JDK 有兼容上限，你用的 Gradle 版本如果不支持 JDK 21，就会直接崩。

所以版本选择要遵循一个原则：以你的 RN 项目里 Gradle Wrapper 指定的 Gradle 版本为准，反推 JDK 版本。RN 项目根目录下有个 android/gradle/wrapper/gradle-wrapper.properties，里面写着 distributionUrl，比如 gradle-8.3-all.zip。Gradle 8.x 一般配 JDK 17 比较稳。你可以先确定这个，再去下对应的 JDK。

Android SDK 这边，核心是三个部分：platform-tools（含 adb）、build-tools（编译打包用）、platforms（对应某个 Android API 级别）。RN 项目里 android/build.gradle 会指定 compileSdkVersion 和 targetSdkVersion，你装的 platforms 版本要能覆盖它。比如项目要求 API 34，你就得装 platforms;android-34。

组件	推荐版本	作用	验证命令
JDK	17（LTS）	编译 Java/Kotlin 代码	java -version
Android SDK Platform-Tools	最新	提供 adb、fastboot	adb version
Android SDK Build-Tools	34.0.0	打包 APK	sdkmanager --list 查看
Android Platform	android-34	对应 API 级别	目录存在即可
Gradle	由项目 Wrapper 决定	构建系统	gradlew --version

这张表建议你搭之前先扫一眼，心里有个数。后面每一步我都会对应到这张表里的某一项。

2.3 环境变量的作用与设置顺序

环境变量是命令行方案的命脉。图形化安装器之所以"黑盒"，很大程度就是因为它偷偷帮你设了环境变量，但设得不全或者设错了。手动设置的好处是你完全掌控，坏处是你得知道每个变量的含义。

核心变量有这么几个：

• JAVA_HOME：指向 JDK 根目录，比如 D:\dev\jdk。Gradle 靠它找 Java。
• ANDROID_HOME：指向 Android SDK 根目录，比如 D:\dev\android-sdk。RN 的构建脚本靠它找 SDK。
• Path：要把 %JAVA_HOME%\bin、%ANDROID_HOME%\platform-tools、%ANDROID_HOME%\cmdline-tools\latest\bin 都加进去，这样你才能在任意目录直接敲 java、adb、sdkmanager。

设置顺序上，先设 JAVA_HOME 和 ANDROID_HOME 这两个独立变量，再在 Path 里引用它们。这样以后你想换 JDK 版本，只改 JAVA_HOME 一处就行，Path 不用动。这是个很实用的小习惯，能省掉大量重复劳动。

提示：改完环境变量后，一定要关掉当前命令行窗口重新开一个，否则新变量不会生效。这是新手最常犯的错，改完变量在当前窗口敲命令发现没反应，以为设置失败了，其实是窗口缓存了旧环境。

3. 从零开始：JDK 与 Android SDK 的命令行安装

3.1 手动部署 JDK 并验证

JDK 的获取方式，我推荐直接用压缩包（zip 或 tar.gz），而不是 exe 安装程序。原因还是那个：安装程序会往注册表、系统目录里写东西，卸载不干净，而压缩包解压即用，想换版本直接删目录换新的，干净利落。

下载对应平台的 JDK 17 压缩包后，解压到 D:\dev\jdk。注意解压后目录里应该直接是 bin、lib、conf 这些，而不是多套一层 jdk-17.0.x。如果多了一层，要么把里面的内容移出来，要么把 JAVA_HOME 指到那一层。我个人习惯是让 JAVA_HOME 直接指向含 bin 的那一层。

设置好 JAVA_HOME 后，开新窗口验证：

正常应该输出类似 openjdk version "17.0.x" 的信息。如果提示"不是内部或外部命令"，说明 Path 没配好，回去检查 %JAVA_HOME%\bin 是否加进去了，以及 JAVA_HOME 本身是否指向了正确目录。

这里有个细节：java -version 输出的是运行时版本，javac -version 输出的是编译器版本，两个都要看。有时候系统里装了多个 Java，Path 顺序不对会导致 java 和 javac 指向不同版本，构建时就会出诡异问题。

3.2 用 cmdline-tools 替代完整 Android Studio

这是整套方案里最关键的一步。Android Studio 体积巨大，但我们真正需要的只是它背后的 SDK 命令行工具。Google 官方提供了 commandlinetools 包，里面包含 sdkmanager、avdmanager 等核心工具，体积只有一百多 MB。

下载 commandlinetools-win-*.zip 后，解压到 D:\dev\android-sdk\cmdline-tools。注意这里有个坑：解压后目录名通常带版本号，比如 cmdline-tools/bin，但 sdkmanager 期望的布局是 cmdline-tools/latest/bin。所以你要手动把解压出来的目录重命名为 latest，或者建一个 latest 目录把内容放进去。

正确的布局应该是：

然后把 %ANDROID_HOME%\cmdline-tools\latest\bin 加进 Path。开新窗口验证：

能输出版本号就说明工具链通了。如果报错说找不到 JAVA_HOME，说明 JDK 那边还没配好，sdkmanager 是依赖 Java 运行的。

3.3 用 sdkmanager 精准安装所需组件

有了 sdkmanager，安装 SDK 组件就是一行命令的事。先看看有哪些可用包：

输出会很长，包含已安装和可安装的。我们按需装几个核心组件：

这条命令会下载并安装 adb、API 34 平台、以及对应的构建工具。安装过程中会提示你接受许可协议，输入 y 回车即可。如果你想一次性接受所有许可，可以：

然后一路 y 下去。这一步很重要，因为 Gradle 构建时如果发现许可没接受，会直接失败，报错信息还不一定直白。

装完之后，D:\dev\android-sdk 下应该出现了 platform-tools、platforms、build-tools 这几个目录。验证 adb：

能输出版本号就对了。如果提示找不到命令，检查 %ANDROID_HOME%\platform-tools 是否在 Path 里。

实操心得：sdkmanager 下载速度受网络影响较大，如果卡住不动，可以尝试在命令后加 --verbose 看详细进度，或者换个时间段再试。另外，build-tools 的版本号要和项目里 build.gradle 指定的版本对得上，装错了版本 Gradle 会提示找不到。

3.4 模拟器与系统镜像：按需安装而非全量

如果你要用模拟器调试，还需要装 emulator 和至少一个系统镜像。系统镜像的命名规则是 system-images;android-<API>;<类型>;<架构>，比如：

这里 google_apis 表示带 Google 服务的镜像，x86_64 是架构。选镜像时要注意，如果你用的是 AMD 处理器，虚拟化加速的配置和 Intel 略有不同，但现代 Windows 上两者都能用。装完之后用 avdmanager 创建虚拟设备：

-n 是设备名，-k 是镜像包名，-d 是设备型号。创建好之后可以用 emulator -list-avds 查看，用 emulator -avd rn_test 启动。

如果你有真机，其实可以跳过模拟器这一整套，直接用 USB 连电脑开调试模式，adb devices 能识别到就行。真机调试比模拟器快得多，也更接近真实表现，我个人更推荐。

4. 让 RN 项目真正跑起来：Gradle 与构建链路打通

4.1 创建或拉取 RN 项目后的第一件事

环境搭好之后，创建一个 RN 项目验证整条链路：

或者用 TypeScript 模板：

项目创建完成后，先别急着 run-android。进到 android 目录，看一眼 gradle/wrapper/gradle-wrapper.properties 里的 Gradle 版本，确认和你装的 JDK 兼容。然后执行：

这一步会触发 Gradle Wrapper 下载对应版本的 Gradle。如果卡在下载不动，多半是网络问题，可以配置国内镜像，或者手动下载 Gradle 压缩包放到 ~/.gradle/wrapper/dists 对应目录下。

gradlew --version 成功输出后，说明 Gradle 本身能跑了，JDK 也认到了。这是构建链路的第一道关卡，过了这关，后面就顺很多。

4.2 构建 APK 时最常见的三类报错

第一次跑 gradlew assembleDebug 或 npx react-native run-android，大概率会遇到报错。我把最常见的三类整理出来，方便你对号入座。

第一类是 SDK 路径找不到，报错里会出现 SDK location not found。原因是 Gradle 没找到 ANDROID_HOME，或者项目根目录下缺少 local.properties。解决办法是在 android 目录下建一个 local.properties，写入：

注意 Windows 路径里的反斜杠要转义成双反斜杠，或者直接用正斜杠 D:/dev/android-sdk 也行。

第二类是 依赖下载失败，报错里出现 Could not resolve 或 Connection timed out。这是网络问题，需要在项目级 build.gradle 里配置镜像仓库。把 google() 和 mavenCentral() 替换或补充为国内可访问的镜像地址，能显著改善下载速度。

第三类是 JDK 版本不匹配，报错里出现 Unsupported class file major version。这说明 Gradle 用的 JDK 和你以为的不一样。可以在 android/gradle.properties 里显式指定：

这样 Gradle 就会强制用这个 JDK，不受系统 Path 里其它 Java 干扰。

报错关键词	根因	解决方向
SDK location not found	未找到 SDK 路径	配 local.properties 或 ANDROID_HOME
Could not resolve	依赖下载失败	配置镜像仓库
Unsupported class file	JDK 版本不匹配	指定 org.gradle.java.home
adb not found	platform-tools 未入 Path	检查环境变量

4.3 启动白屏问题的排查思路

RN 应用装到设备上之后启动白屏，是另一个高频问题。白屏的本质是 JS Bundle 没加载成功，或者加载了但渲染出错。排查要分两层：一层是原生层有没有正常启动，另一层是 JS 层有没有报错。

先看原生层。用 adb logcat 抓日志：

只看 Error 级别。如果看到 Unable to load script 之类的，说明 Bundle 没找到。开发模式下，Bundle 是由 Metro 打包服务器提供的，所以你要确认 Metro 在跑（npx react-native start），并且设备能访问到你的电脑。真机的话，需要 adb reverse tcp:8081 tcp:8081 把端口反向映射过去，这样设备上的 localhost:8081 才能通到电脑。

如果原生层没问题，日志里能看到 React Native 的启动信息，那白屏多半是 JS 层抛异常了。这时候打开 Metro 的终端，或者用 adb logcat 过滤 ReactNativeJS 标签，能看到具体的 JS 报错。常见的有组件导入路径错误、某个原生模块没链接、或者第三方库版本不兼容。

实操心得：白屏排查最有效的工具其实是 adb logcat 配合 Metro 终端。很多人只盯着手机屏幕看，什么信息都得不到。养成开两个终端、一个跑 Metro 一个跑 logcat 的习惯，问题定位速度会快很多。另外，adb reverse 这条命令在真机调试时几乎必用，但很多人不知道，导致一直以为是代码问题。

4.4 用命令行管理设备与端口

纯命令行方案里，设备管理也全靠 adb。几个高频命令值得记牢：

adb reverse 这个命令特别值得说。它的作用是把设备上的某个端口流量转发到电脑的对应端口。RN 开发时 Metro 跑在电脑的 8081 端口，设备要加载 Bundle 就得访问这个端口。模拟器通常能直接访问宿主机，但真机不行，必须靠 adb reverse。这条命令在每次设备重连后都要重新执行，所以建议写进你的启动脚本里。

端口占用也是常见问题。8081 被别的程序占了，Metro 起不来。查端口占用：

找到 PID 后用 taskkill /PID <pid> /F 干掉。或者干脆让 Metro 换个端口启动，npx react-native start --port 8082，然后 adb reverse tcp:8082 tcp:8082 对应改一下。

5. 命令行方案的长期维护与效率提升

5.1 多版本 SDK 与 JDK 的切换策略

做 RN 开发时间长了，你手里可能同时有好几个项目，分别依赖不同的 JDK 和 SDK 版本。这时候如果环境变量是全局写死的，切换起来就很痛苦。我的做法是用脚本按项目切换。

具体来说，为每个项目写一个 env.bat 或 env.ps1，在里面临时设置 JAVA_HOME 和 ANDROID_HOME，然后启动命令行。这样不同项目用不同环境，互不干扰。比如：

双击这个脚本，就进入了一个专属该项目的命令行环境。这个技巧在需要频繁切换版本时特别省心，比反复改系统环境变量靠谱得多。

5.2 把重复命令沉淀成脚本

搭建过程中有很多命令是重复的，比如启动 Metro、反向映射端口、安装应用、抓日志。与其每次手敲，不如沉淀成几个脚本。我常用的有这么几个：

• start-metro.bat：启动 Metro 打包服务
• run-android.bat：执行 adb reverse 加 npx react-native run-android
• log.bat：adb logcat 过滤关键标签

这些脚本不需要多复杂，几行命令就行，但能省掉大量重复输入，也避免记错命令。尤其是 adb reverse 这种容易忘的，写进脚本里就不会漏。

5.3 磁盘清理与 SDK 瘦身

命令行方案的一大优势是可控，但用久了 SDK 目录也会膨胀。sdkmanager 装的每个平台、每个 build-tools 版本都占空间，旧版本留着没用。定期清理：

看看装了哪些，不需要的用：

卸载掉。另外，Gradle 的缓存目录 ~/.gradle/caches 也会越滚越大，里面存着各种依赖的副本。这个目录可以定期清，但清完下次构建会重新下载，所以建议在换项目或长时间不用时再清。

提示：清理 Gradle 缓存前，确认当前没有正在进行的构建，否则可能删到一半导致构建失败。清理命令是直接删目录，Windows 下用 rmdir /s /q %USERPROFILE%\.gradle\caches。

5.4 命令行环境下的调试体验优化

纯命令行不代表调试体验就差。恰恰相反，配好之后效率可能比图形界面还高。几个提升体验的点：

一是把常用命令做成别名。PowerShell 里可以用 Set-Alias，CMD 里可以用 doskey。比如把 adb logcat *:E 设成 loge，敲起来快很多。

二是善用 adb shell 直接进设备。有时候需要看设备上的文件、改权限、跑命令，adb shell 进去比在图形界面点来点去直接得多。

三是日志过滤。adb logcat 输出量巨大，一定要加过滤条件。可以按标签过滤 adb logcat ReactNativeJS:V *:S，只看 JS 相关日志，其它全部静默。这个技巧在排查 JS 层问题时极其有用。

四是配合轻量编辑器。VS Code 加 RN 插件，代码提示、跳转、调试都够用，完全不需要重量级 IDE。整个开发环境加起来占用空间可能只有完整 Android Studio 方案的几分之一。

6. 我在这套方案上踩过的几个真实坑

第一个坑是路径里的空格。我一开始把 SDK 装在 C:\Program Files\Android 下，结果 sdkmanager 执行到一半就退出，没有任何有用报错。折腾了很久才意识到是空格问题。后来全部挪到 D:\dev 下，问题消失。这个教训让我养成了所有开发工具都放纯英文无空格路径的习惯。

第二个坑是环境变量改了但没重开窗口。有次配好 ANDROID_HOME，在当前窗口敲 adb 死活找不到，以为配错了，反复检查环境变量设置界面，折腾半小时。后来随手开了个新窗口，一切正常。从那以后我改完环境变量第一件事就是关窗口重开。

第三个坑是Gradle 和 JDK 版本错配。项目里 Gradle Wrapper 是 7.x，我系统 JDK 是 21，构建时报 Unsupported class file major version 65。查了半天才知道 Gradle 7.x 不支持 JDK 21。解决办法是在 gradle.properties 里指定 org.gradle.java.home 指向 JDK 17。这个坑的隐蔽之处在于，报错信息不会直接告诉你"JDK 太新了"，而是抛一个类文件版本号，得自己去查这个号对应哪个 Java 版本。

第四个坑是真机调试忘了 adb reverse。应用装上去启动白屏，logcat 里显示连不上 8081。我以为是 Metro 没起，检查了半天 Metro 是好的。最后才想起来真机需要 adb reverse。这个命令在模拟器上通常不需要，所以从模拟器切到真机时特别容易忘。

第五个坑是许可协议没接受。sdkmanager 装组件时如果没接受许可，Gradle 构建会失败，报错信息里有一句 You have not accepted the license agreements。解决办法就是跑一次 sdkmanager --licenses 全部接受。这个坑在新机器上第一次搭建时几乎必踩。

这些坑的共同点是：报错信息都不够直白，需要你对整条工具链有整体认知才能快速定位。这也正是命令行方案的价值所在——你越了解每个环节，排查就越快。图形化安装器把这些环节藏起来了，出问题时你反而无从下手。

7. 关于这套方案的一些个人体会

用命令行搭 RN 安卓环境，前期确实比点安装器麻烦，得多敲不少命令，得多理解几个概念。但这份麻烦是一次性的，换来的是长期的可控性。环境出问题时，你知道去哪里找、改哪个文件、验证哪条命令，而不是对着一个图形界面干瞪眼。

我现在维护着好几个 RN 项目，每个项目的 JDK 和 SDK 版本要求都不一样。靠的就是前面说的按项目切换环境的脚本，加上一套沉淀下来的常用命令。整个开发环境占用空间不到 10GB，启动构建的速度也比以前用完整 IDE 时快不少。

如果你正准备搭 RN 环境，又不想被安装器绑架，不妨按这篇文章的步骤走一遍。过程中遇到报错别慌，先看报错关键词，对照第 4 章那张表定位，再用 adb logcat 和 Metro 终端抓细节。搭通一次之后，这套流程就变成肌肉记忆了，以后换机器、换项目，半小时就能重建一套干净的环境。