企业官网建设流程全解析

每次有人问我“配置ReactNative环境难吗”，我第一反应都是：难的不是某个工具安装，而是它们总在互相打架。ReactNative 环境配置牵扯到 Node.js、JDK、Android SDK、Gradle 好几套工具链，任何一个环节版本对不上，都会在创建第一个程序时给你点颜色看看。这篇文章不打算复制官方文档，我会按自己亲手搭建、也帮别人补救过无数次环境的经验，把从零配置到第一个 App 落地的完整过程讲清楚。无论你是从 Web 前端转过来的同学，还是刚接触移动开发的新手，跟着这个流程走下去，大概率能在半小时左右让代码跑到模拟器上。

1. 环境配置的整体思路与版本选择

1.1 React Native 环境究竟需要有哪几块

很多新手容易把 ReactNative 当成一个“框架装完就行”，但实际上它是 JS 与原生代码的桥梁。你写的 JS/TS 代码，要由 Node.js 配合 Metro 打包器负责转译和提供调试服务；最终编译成 Android 安装包时，又绕不开 JDK、Android SDK、Gradle 这一套 Java 生态工具。如果做 iOS 开发，还必须有 Xcode，不过绝大多数配置教程都以 Android 为主线，因为 Windows 也能完成，我也以 Android 为主来讲。

你可以把整套环境想象成开一家店：Node.js 是后厨的菜刀和炉灶，负责把食材切好炒熟；JDK 是厨师资格证书，缺了它厨房根本不让你开火；Android SDK 是食材供应商，给你提供 Android 系统独有组件；Gradle 则是店里的传菜机器人，把各个菜按顺序送到前台。哪个环节掉链子，你的“第一个程序”就端不上来。理解这个关系，后续看报错时会冷静不少。

实际配置时还有个容易忽视的点：React Native 项目里藏着两套代码：一套是你自己写的 JS，一套是官方模板生成的原生壳。原生壳每次构建都需要 Android SDK 和 Gradle 参与，所以就算你只想写一个“Hello World”，也必须把整个原生工具链准备好，省不了。

1.2 版本选型：别看到新版本就往上冲

装环境最忌讳的是一股脑全装最新。官方文档一般会给“最低要求”和“推荐版本”，但组件间有微妙的兼容性。以我常用的组合为例：

有个非常重要的原则：优先使用 React Native 官方模板锁定的 Gradle 和 Android Gradle Plugin 版本。很多人手动升级 Gradle，结果构建直接崩了。原因是 RN 在发布时会针对特定 AGP 版本做测试，你单独升某个组件，等于打破了一套已经调好的组合拳。写代码嘛，稳定压倒一切。

如果你手头已经有别的项目，最好先查一下它们需要的 Node 版本。我在工作中会同时维护三四个 RN 项目，有的老项目必须用 Node 16，这时候建议用 nodenv 或 nvm-windows 做版本切换，而不是反复卸载重装。不过第一次上手阶段，直接装一个满足要求的新 LTS 就够用了。

1.3 不同操作系统下的路径差异

Windows、macOS、Linux 的环境配置大同小异，真正的差异集中在环境变量和 SDK 默认路径上。Windows 上，Android SDK 默认安装到C:\Users\你的用户名\AppData\Local\Android\Sdk；macOS 上通常放在~/Library/Android/sdk；Linux 则常有自定义路径。

环境变量这块，Windows 要走“系统属性 → 环境变量”，macOS 或 Linux 要改~/.zshrc或~/.bashrc，改完还要source一下才能生效。新手最容易在“明明配了环境变量，新终端却不认”这件事上栽跟头。这是因为终端进程是在环境变量修改前启动的，已经缓存的旧配置不会自动刷新，关掉终端重新开一个就正常了。

另外，硬盘空间要留足，Android Studio、SDK 系统镜像、Gradle 缓存加起来轻松超过 10GB。如果 C 盘紧张，可以在安装时指定别的盘符，并把 SDK 路径一并改过去。我不建议在路径里带中文或空格，有些原生工具链对这类路径处理很不好，后续会莫名报一些诡异错误。

2. 动手安装底层依赖

2.1 Node.js 安装与 npm 镜像配置

Node.js 的安装最没技术含量，但有细节。官网下载 LTS 版安装包，Windows 用户记得安装时勾选“Add to PATH”，macOS 用户下载 pkg 后一路下一步即可。装完打开终端，输入node -v和npm -v，看到版本号说明成功了。

如果提示“不是内部或外部命令”，大概率是 PATH 没配好。Windows 下可以手动把 Node 安装目录加到系统 PATH，比如C:\Program Files\nodejs\。这里提醒一句，有些安装器会同时帮你装一个老版本 npm，如果发现npm -v和 Node 版本差距过大，可以执行npm install -g npm@latest升级到新的 npm。

国内网络环境下，建议先把 npm 镜像切到国内源。我不太喜欢用那种全量替换注册表的方式，但这一步确实能显著提升依赖下载速度。命令行敲这两句：

npm config set registry https://registry.npmmirror.com npm config get registry

执行后如果看到https://registry.npmmirror.com，说明镜像源配置成功。后面初始化 RN 项目时，几十个依赖包瞬间就能拉完，不然卡在进度条上会非常难受。用 yarn 也一样，可以执行yarn config set registry https://registry.npmmirror.com来设置。

2.2 JDK 安装与环境变量配置

RN 对 JDK 版本有硬性要求。我用的是 OpenJDK 17，你可以去 Adoptium 官网下载 Temurin 17，也可以直接用 Android Studio 内置的 JBR，但那样容易把环境搞乱，还是单独装一份最靠谱。

安装完成后，需要设置JAVA_HOME环境变量并把它加到 PATH。Windows 用户在系统环境变量里新建JAVA_HOME，值填 JDK 安装目录，比如C:\Program Files\Eclipse Adoptium\jdk-17.0.xx。然后再编辑 Path，新增%JAVA_HOME%\bin。macOS 上则在~/.zshrc里写入：

export JAVA_HOME=$(/usr/libexec/java_home -v 17) export PATH=$JAVA_HOME/bin:$PATH

配置完重新开终端，执行java -version，看到版本 17 就说明成功。大部分人喜欢在 Android Studio 里点一点，但只改项目设置是不够的，命令行工具和 Gradle 很难直接继承 IDE 里的配置，所以系统级环境变量才是更稳妥的方案。这个细节和git安装及配置教程里反复强调“配置 global 和 local 用户信息要分清”是同一个道理，一个管系统，一个管项目，各司其职才不出乱子。

2.3 Android Studio 与 Android SDK 准备

Android Studio 是新手的“定海神针”，也是我见过的环境配置里最耗时的一环。去官网下载最新稳定版，安装时建议选择 Standard 安装，它会帮你把 Android SDK、Platform-Tools、模拟器管理工具全部拉齐。如果空间有限，也可以自定义组件，但至少要保证有 Android SDK Platform-Tools。

装好后第一件事是打开 SDK Manager，确认这几个组件已经安装：

• Android SDK Platform 对应你目标系统版本
• Android SDK Build-Tools
• Android SDK Platform-Tools（包含 adb）
• Intel HAXM 或 Windows Hypervisor Platform（模拟器加速）

SDK 下载同样可能遇到网络慢的问题，可以在 Android Studio 的 HTTP Proxy 设置里配置国内镜像，也可以用命令行工具sdkmanager来安装指定包。很多人问我要不要装所有 API Level，真不用，占空间又容易把工具链弄乱，装单个稳定版本就够了。

接下来配置ANDROID_HOME环境变量。Windows 用户新建系统变量ANDROID_HOME，值指向 SDK 路径，比如C:\Users\<用户名>\AppData\Local\Android\Sdk。再往 PATH 里加上两个路径：%ANDROID_HOME%\platform-tools和%ANDROID_HOME%\emulator，这样命令行里才能直接用adb和emulator命令。macOS 则是在 shell 配置文件里加：

export ANDROID_HOME=$HOME/Library/Android/sdk export PATH=$PATH:$ANDROID_HOME/platform-tools

2.4 Git 安装与基础配置

Git 不是跑 React Native 的必要条件，但项目从创建开始就应该纳入版本管理，所以我还是建议顺手装上。Windows 用户下载 Git for Windows，安装时一路默认即可，唯一注意的是在“调整 PATH 环境”这一步选择“从命令行使用 Git”，否则以后在 cmd 和 PowerShell 里可能调不到git命令。

装好后配置两行个人身份信息，这是提交代码的基础：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

很多初学者容易忽略后续从 GitHub 拉旧项目时 SSH 密钥的问题。配置git本身不难，真正麻烦的是密钥认证。如果你准备长期搞开发，建议提前生成 SSH Key 并添加到代码托管平台，避免每个项目都输一次用户名密码。

3. 初始化第一个 React Native 项目

3.1 使用 CLI 模板创建项目

按要求装完底层依赖后，终于到了令人愉悦的部分。打开终端，进入你想放代码的目录，执行：

npx @react-native-community/cli@latest init FirstApp

这里用npx而不是全局安装 CLI，能保证每次都用最新官方模板，也避免全局命令版本过老影响项目。项目名建议用驼峰命名，比如FirstApp、ShopApp，不要包含中文、连字符或数字开头，否则 Android 包名和目录名都会出现奇怪问题。

执行后 CLI 会开始拉取模板、安装 npm 依赖，第一次可能要等几分钟，控制台会打印一些“Installing dependencies”的日志。这个过程千万别去反复 Ctrl+C，依赖安装没完成的话，项目结构会是残缺的，后面怎么修都别扭。

如果初始化过程中卡在“installing pods”这样的字样，并且你不是在 macOS 上做 iOS 开发，可以直接忽略或等它超时。CLI 默认会在 macOS 上尝试安装 CocoaPods，Windows 上不存在这一步。初始化结束后，进入项目目录看看文件列表，你会见到一个结构清晰的 RN 项目。

3.2 读懂生成出来的项目目录

FirstApp/ ├── android/ # Android 原生工程 ├── ios/ # iOS 原生工程 ├── node_modules/ # npm 依赖 ├── App.tsx # 主界面组件 ├── index.js # JS 入口文件 ├── package.json # 项目依赖声明 ├── metro.config.js # Metro 打包配置 └── tsconfig.json # TypeScript 配置

新手最容易盯着android文件夹发呆，不知道里面到底是什么。简单说，android/app/src/main/java/com/firstapp/MainActivity.kt就是原生入口，Android 系统启动 App 时先加载这个 Activity，再由它加载 JS bundle。android/app/build.gradle里可以改 applicationId 和版本号，平时这类原生文件基本不该碰，除非你要调整图标或包名。

package.json则是整个项目的中枢，里面记录了react-native和react的版本号，还有 npm scripts。我在多台电脑之间切换时，只要新旧机器的 Node 和 JDK 版本一致，执行npm install就能完全复现环境。这种“依赖锁版本”的思路，和配置 Java/Python 环境时强调“版本一致性”是相通的，热词里那些maven环境配置、hbase安装与配置之所以难，一大半坏在版本失控上。

3.3 让第一个程序在模拟器上跑起来

启动模拟器这一步值得单独讲讲。打开 Android Studio，找到 Device Manager 面板，点击 Create Device，选择一个手机型号模板，我习惯用 Pixel 系列，分辨率统一，性能也好。然后选择系统镜像，比如 API 34，点击 Download 下载完成后，按 Next 完成创建。首次启动模拟器会比较慢，以后会快很多。

模拟器起来后，在项目根目录执行：

npm run android

这个命令做了两件事：启动 Metro 打包服务，同时用 Gradle 构建原生 Android 应用。如果一切顺利，控制台上会看到BUILD SUCCESSFUL，随后模拟器自动安装并打开你的 App，屏幕中央出现一行默认文字。

第一次构建最费时间，Gradle 要下载，依赖要编译，五到十分钟都很正常。期间如果卡在某个百分比半天不动，十有八九是网络问题，下文会讲怎么处理。当应用成功跑起来后，你可以去App.tsx里把默认文本改成自己写的“你好，React Native”，按一下 R 键（模拟器内）重新加载，界面就会更新。这大概就是“环境配置成功”的最好证明。

4. 常见问题与排查实录

4.1 Metro 服务端口占用和缓存异常

Metro 默认监听 8081 端口。如果之前有项目没关干净，端口被占用，启动时会报Error: listen EADDRINUSE。这种情况不要重启电脑，找到占用者杀掉即可。Windows 下执行：

netstat -ano | findstr :8081 taskkill /F /PID 这里填进程号

macOS 下用lsof -i :8081找 PID，再kill -9 进程号。如果端口没被占，但页面一直加载不出来，多半是 Metro 缓存出问题，可以执行npx react-native start --reset-cache重启服务。我几乎每次切换分支后都会做一次缓存清理，这套动作能解决一大批“明明代码改了却没反应”的玄学问题。

4.2 Gradle 下载慢和构建失败

Gradle 是另一个网络重灾区。首次构建时 Gradle wrapper 要下载，Android 依赖要从 Google 和 Maven Central 拉取，国内网络慢是常态。解决办法分两步。

第一步，修改android/gradle/wrapper/gradle-wrapper.properties里的distributionUrl。如果官方地址太慢，可以换成腾讯云镜像：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.10.2-bin.zip

第二步，在android/build.gradle文件的 allprojects repositories 中添加国内镜像：

allprojects { repositories { maven { url 'https://maven.aliyun.com/repository/google' } maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } google() mavenCentral() } }

改完后重新执行npm run android。我也使用过把整个 Gradle 用户目录从 C 盘迁到别的盘的做法，具体是在系统变量里新增GRADLE_USER_HOME，这样可以避免C:\Users\xxx\.gradle越来越大。热词里那些pytorch环境搭建、ubuntu搭建qt开发环境之类的问题，核心也多是镜像源和依赖缓存，RN 这边只是换了个工具名而已。

4.3 SDK 未找到和设备连接问题

如果构建时出现SDK location not found，说明 Gradle 找不到 Android SDK。最简单的修法是在android/目录下手动创建local.properties，写入：

sdk.dir=C\:\\Users\\你的用户名\\AppData\\Local\\Android\\Sdk

注意路径里的反斜杠要转义。这个文件一般会被.gitignore忽略，所以从仓库 clone 下来的项目不会带着它，每次换机器或换账号都必须重新生成。如果你始终找不到 SDK 路径，Android Studio 打开过项目后会在右下角提示安装缺失组件，按提示操作也行。

真机调试时，先在手机里开启“开发者选项”和“USB 调试”，插上电脑后执行adb devices，能看到一串设备 ID 且带device后缀才算连上。连接成功后，USB 模式下的 Metro 访问还需要一条反向路由，执行：

adb reverse tcp:8081 tcp:8081

然后再npm run android。我见过不少人模拟器里跑得好好的，一换真机就白屏，多半就是漏了这一步。

4.4 高频环境变量问题速查

这条速查表我基本每次指导别人都发一遍。记住一个原则：遇到报错先读前 30 行，不要只看最后一行。很多时候真正的原因在上面的日志里，最后一行只是结果。

5. 从环境配置走向日常开发的经验

5.1 固定好一套组合拳，少折腾

配置完环境不是终点，后续还要长期维护。对我来说，最省心的方法是尽量保持 Node、JDK、Android SDK、Gradle 的版本组合在一个“已知可用区间”内。比如团队项目里确定 Node 用 18 LTS、JDK 用 17、Android 系统镜像用 API 34，那就所有人统一，别某个人悄悄升了 Node 20 引发潜在问题。

如果你要同时维护多个项目，可以考虑在项目根目录添加一个.nvmrc文件，内容写18，这样进入目录时 nvm 或 nodenv 能自动切换 Node 版本。虽然多一步配置，但非常值得。这与ubuntu 24.04 lts配置教程等环境类教程里“先定基线再干活”的思路一样，环境乱套往往是因为基线不清晰。

5.2 把日志英文当线索，别硬碰硬

最后分享一个我实际带人时总强调的观点：报错不是在找茬，而是在提供线索。React Native 环境配置的坑，绝大多数是另一批人早就踩过的常见坑。比如Could not find or load main class多半是 JDK 版本不对，SDK map platform components missing多半是 SDK 组件没装齐。把这些关键词复制到搜索引擎或官方 issue 区，答案几乎立刻出来。

我见过太多人卡住后第一反应是“把环境卸了重装”，其实治标不治本。我更推荐的做法是，在报错现场多停一会儿，把日志前十行认真读一遍，再对照上面这张速查表去定位。环境这东西，一次配好之后很少再出大问题，真正频繁出问题的，反而是那些没耐心看日志、反复重装的人。第一次搭建多花十分钟理清工具链关系，后面开发就能把时间全部花在写业务上，这才是这件事最划算的地方。