Mac 从零搭建 React Native 开发环境：完整方案 + 踩坑实录

本文的含金量：所有步骤与坑位均在Apple Silicon Mac（macOS 26）+ 国内裸网络环境下于 2026-10 真实搭建并通过，最终 RN 0.88.1 项目在 iOS / Android 双模拟器成功运行。文中 9 个卡点全部是实测踩到、实测解决的，不是抄网上的理论文。

适用读者：Mac 新手 / 前端转 RN 的同学。每一步都写清「做什么 → 为什么 → 怎么确认成功」。

目录

一、开工前的认知

1、React Native 环境由哪几块组成

2、总路线图

二、搭建方案

1、确认芯片类型

2、安装 Homebrew 并立刻换国内镜像

3、nodeJS + npm 国内镜像

4、Watchman

5、iOS 侧（Xcode + 运行时 + CocoaPods）

5.1、安装 Xcode

5.2、首次配置（装完 Xcode 执行一次）

5.3、下载 iOS 模拟器运行时（Xcode 装完 ≠ 模拟器能用，需单独下载）

5.4、CocoaPods

6、Android 侧（JDK -> Studio -> SDK -> 环境变量）

6.1、JDK 17（⚠️ 这里 90% 的人会踩卡点②）

6.2、安装 Android Studio（手动 GUI 操作）

6.3、创建模拟器 AVD

6.4、配置环境变量（RN 命令行靠它找到 adb / 模拟器）

7、创建 RN 项目

8、把 Gradle 下载源切换成 腾讯镜像（Android 构建前必做）

9、跑通 Android（重点部分，4个卡点连环）

9.1、构建并安装 App

9.2、构建并安装 App

9.3、手动启动 Metro （大概率不会自动启动，见卡点⑤）

9.4、处理权限弹窗（见卡点⑥）

9.5、授权本地网络访问（Android 16 模拟器专属，终极卡点，见卡点⑦）

9.6、终极验收

10、跑通 iOS

三、踩坑实录

1、brew 下载极慢，一个包卡十几分钟

2、brew install --cask temurin@17 装 JDK 永远卡死（镜像救不了它）

3、Xcode 装好了，模拟器却一个设备都没有

4、首次构建卡在 "Downloading gradle-x.x"

5、App 装上了，Metro 却没起来（CLI 不吭声地失败了）

6、权限弹窗每次启动都来捣乱

7、Android 16 上 App 死活连不上 Metro——全网新坑，静默无报错（压轴）

8、首次构建 20 多分钟，是不是卡死了？

9、后台进程莫名消失 / 终端一关全没了

四、卡点速查表

五、日常开发工作流

附录A：~/.zshrc 环境变量汇总

附录 B：最终版本清单(以本机为例)

一、开工前的认知

1、React Native 环境由哪几块组成

双平台 = 两套完全对立的工具链。只先做一个平台完全可以(建议先 Android，坑少；或先iOS，不用装JDK那堆)。

2、总路线图

brew+镜像 → Node → Watchman → 【iOS】Xcode → 运行时 → CocoaPods
→ 【Android】JDK17 → Android Studio → SDK/AVD → 环境变量
→ 创建项目 → 换 Gradle 镜像 → 跑 Android → 跑 iOS

二、搭建方案

1、确认芯片类型

uname -m

• 输出arm64→ Apple Silicon（M1/M2/M3/M4），本文默认这种
• 输出x86_64→ Intel 芯片，下文所有涉及"选 arm64"的地方换成 x86_64

2、安装 Homebrew 并立刻换国内镜像

# 1. 安装（过程中可能要求输入开机密码，输入时屏幕不显示，正常） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 2. Apple Silicon 装完按屏幕提示把 brew 加入 PATH（它会打印两行 eval 命令让你执行） # 3. ★立刻换中科大镜像（写进配置文件，永久生效） cat >> ~/.zshrc <<'EOF' # Homebrew 国内镜像（中科大） export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles" EOF source ~/.zshrc

✅ 验收：brew --version有版本号输出。

⚠️ 为什么第一步就换镜像？见卡点①。brew 的包分两种（后面反复用到这个概念）：

• formula：编译好的"瓶装"包（bottle），✅ 走上面的镜像，速度飞快
• cask：各种 dmg/pkg 图形安装包，❌不走镜像，卡点②的元凶

3、nodeJS + npm 国内镜像

brew install node@22 # npm 换淘宝镜像（所有 npm 下载都提速） npm config set registry https://registry.npmmirror.com

✅ 验收：node -v（≥ 18，RN 0.8x 建议 20+）、npm config get registry显示 npmmirror。

已有 Node 直接用即可，本文实测 Node 24 也没问题。

4、Watchman

brew install watchman

✅ 验收：watchman --version。

5、iOS 侧（Xcode + 运行时 + CocoaPods）

5.1、安装 Xcode

AppStore 中 搜 “Xcode” 下载安装即可（软件大小约 10G）

⚠️注意：React Native 需要完整版，不要装成 “Xcode Command Line Tools”

5.2、首次配置（装完 Xcode 执行一次）

# 指定活跃的 Xcode 开发者目录路径 sudo xcode-select -s /Applications/Xcode.app/Contents/Developer # 自动接受 Xcode 软件许可协议 sudo xcodebuild -license accept

5.3、下载 iOS 模拟器运行时（Xcode 装完 ≠ 模拟器能用，需单独下载）

这是 iOS 侧最大的隐藏坑（详见卡点③）。可执行以下命令：

# 约 8GB，下载 + 安装可能要 20~60 分钟 xcodebuild -downloadPlatform iOS

或者 在 Xcode 中下载：

Xcode → Settings（⌘+,）→ Platforms → iOS -> GET

✅ 验收：

xcrun simctl runtime list # 应显示 iOS xx.x ... (Ready) xcrun simctl list devices available | grep iPhone # 应列出一串 iPhone

5.4、CocoaPods

brew install cocoapods

✅ 验收：pod --version。

为什么用 brew 不用官方的sudo gem install cocoapods？Mac 自带的系统 Ruby 又老又受系统保护，用 sudo 往里装 gem 容易把 Ruby 环境搞坏，macOS 大版本升级后经常整个坏掉。brew 会带一份自己的 Ruby 干净隔离。

6、Android 侧（JDK -> Studio -> SDK -> 环境变量）

6.1、JDK 17（⚠️ 这里 90% 的人会踩卡点②）

不要用brew install --cask temurin@17（实测 2KB/s 卡死）。正确姿势用 formula 版：

brew install openjdk@17 # 配置环境变量 cat >> ~/.zshrc <<'EOF' # JDK 17（brew openjdk@17） export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" export PATH="$JAVA_HOME/bin:$PATH" EOF source ~/.zshrc

✅ 验收：java -version显示openjdk version "17.x.x"。

Temurin 和 OpenJDK 对 RN 完全等价（Android 编译器只认"JDK 17"，不挑发行版）。 可选增强：让系统级探测也能发现它（需输密码）：sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

6.2、安装 Android Studio（手动 GUI 操作）

1、官网 developer.android.com 下载 dmg（Apple Silicon 选 arm64 版），拖进 Applications

2、首次打开走 Setup Wizard，全部默认（自动装 SDK、platform-tools、emulator）

3、更多操作（More Actions）→SDK Manager，确认勾选：

• Android SDK Platform（跟 RN 版本走，0.88 要 API 36/37，装新不装旧）
• SDK Build-Tools（对应版本）
• Android SDK Platform-Tools、Android Emulator

6.3、创建模拟器 AVD

More Actions →Device Manager→ Create Device → 选个 Pixel → 选系统镜像时Apple Silicon 必须选带arm64标记的（选错成 x86_64 会卡成 PPT 或直接起不来）。

6.4、配置环境变量（RN 命令行靠它找到 adb / 模拟器）

cat >> ~/.zshrc <<'EOF' # Android SDK（React Native） export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools" EOF source ~/.zshrc

✅ 验收：

adb version # 有输出即 PATH 生效 emulator -list-avds # 显示你刚创建的模拟器名字

7、创建 RN 项目

mkdir -p ~/rn-playground && cd ~/rn-playground npx @react-native-community/cli@latest init MyApp --skip-install cd MyApp npm install # 已配 npmmirror，实测 857 个包 59 秒

✅ 验收：cat package.json看到react-native: 0.8x.x。

8、把 Gradle 下载源切换成 腾讯镜像（Android 构建前必做）

打开MyApp/android/gradle/wrapper/gradle-wrapper.properties

把

distributionUrl=https\://services.gradle.org/distributions/gradle-X.X.X-bin.zip

替换成

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

也可在控制台执行以下指令 直接切换

cd MyApp/android sed -i '' 's|services.gradle.org/distributions|mirrors.cloud.tencent.com/gradle|' gradle/wrapper/gradle-wrapper.properties

不换的后果：首次构建卡在 "Downloading gradle-x.x" 十几分钟到永远。实测换完 148MB 秒下。

9、跑通 Android（重点部分，4个卡点连环）

9.1、构建并安装 App

方案A：在 Android Studio -> Device Manage -> "▶️"

方案B：执行以下指令

emulator -avd 模拟器名字

✅ 验收：adb devices显示emulator-xxxx device。

9.2、构建并安装 App

cd ~/rn-playground/MyApp npm run android

首次构建 20 分钟左右完全正常（详见卡点⑧），中途会自动下载安装 NDK、CMake 等，看到最终：

BUILD SUCCESSFUL in XXm XXs
Installed on 1 device.

9.3、手动启动 Metro （大概率不会自动启动，见卡点⑤）

# 新开一个终端窗口 cd ~/rn-playground/MyApp npm start

✅ 验收：浏览器访问http://localhost:8081/status显示packager-status:running。

9.4、处理权限弹窗（见卡点⑥）

App 首次启动可能弹「允许 MyApp 查找并连接到附近设备？」-- 点击 Dont‘t allow/不允许 即可。嫌烦的话可执行以下指令，永久禁用。

adb shell pm grant com.myapp android.permission.BLUETOOTH_SCAN

9.5、授权本地网络访问（Android 16 模拟器专属，终极卡点，见卡点⑦）

如果你满足：模拟器是 Android 16 / API 36+且 App 一直报 "Unable to load script / Make sure you're running Metro"，执行：

adb shell appops set com.myapp ACCESS_LOCAL_NETWORK allow

然后重启 App（模拟器上划掉重开，或）

adb shell am force-stop com.myapp && adb shell am start -n com.myapp/.MainActivity

9.6、终极验收

# 看 App 日志出现这行 = bundle 加载成功，界面必然渲染 adb logcat -d | grep ReactNativeJS | tail -1 # 期待输出：I ReactNativeJS: Running "MyApp" with {"rootTag":1,...,"fabric":true}

模拟器屏幕显示"Welcome to React Native / Version: 0.88.x / 💡 Open App.tsx to get started"—— 🎉 Android 全通！

10、跑通 iOS

cd ~/rn-playground/MyApp cd ios && pod install && cd .. # 首次必做：下载 iOS 原生依赖（走 CDN，慢就挂代理） npm run ios # 自动选一个 iPhone 模拟器编译运行

✅ 验收：iPhone 模拟器弹出，显示同样的 RN 欢迎页。

iOS 侧优势：不用 Metro 折腾（模拟器和 Mac 同机，天然连通）、不涉及本文大部分卡点。

三、踩坑实录

1、brew 下载极慢，一个包卡十几分钟

• 现象：brew install cocoapods卡在Downloading ruby (4.0.9)，进度纹丝不动，等 15 分钟只下了几百 KB。

• 原因：brew 的二进制包默认从 GitHub 的容器仓库ghcr.io下载，国内直连质量极差。

• 解法：配中科大镜像（步骤 1 已做）：

export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"

配完同一个包秒下。清华 TUNA 镜像同理可用。

• 预防：装完 brew 第一件事就是换镜像，别等卡住了再找原因。
• 注意：卡住时Ctrl+C中断重跑是安全的，brew 支持续传，不会损坏。

2、brew install --cask temurin@17装 JDK 永远卡死（镜像救不了它）

• 现象：换完镜像后装 JDK 依然 2KB/s，3 分钟下了 352MB 包里的 352KB。有人以为是镜像没配对，反复折腾。

• 原因：镜像只加速 formula（bottle），不加速 cask。temurin@17 是 cask，它的安装包（180MB 的 pkg）托管在 GitHub Release（release-assets.githubusercontent.com），恰好又是国内最烂的域名之一。

• 解法：放弃 cask，改装 formula 版 OpenJDK（功能对 RN 完全等价）：

brew install openjdk@17

bottle 走镜像秒装，还不需要 sudo、不弹安装器。

• 方法论：brew 里一个软件可能同时有 cask 和 formula 两个版本，国内网络永远优先 formula；只有 formula 不存在的（如 Android Studio、微信这类 GUI App）才用 cask，且 cask 慢就别死等——去官网手动下载 dmg。

3、Xcode 装好了，模拟器却一个设备都没有

• 现象：npm run ios或打开 Simulator 报错；xcrun simctl list devices available列表为空。

• 原因：iOS 模拟器运行时是独立组件（约 8GB，相当于模拟器里的"iOS 操作系统"），App Store 装 Xcode 本体（10GB）不会自动带上它。

• 解法：xcodebuild -downloadPlatform iOS，或 Xcode → Settings → Platforms 里手动下载。

• 实测细节：

  • 下载进度可看这个文件的大小（很黑客但很好用）：/System/Library/AssetsV2/downloadDir/com_apple_MobileAsset_iOSSimulatorRuntime.*/AssetData/Restore/*.dmg

  • 支持断点续传：中途断网/中断，重跑同一条命令从断点继续，不会重头下。

  • 下载完成 ≠ 立即可用，还有几分钟静默安装期，runtime list显示(Ready)才算好。

• 预防：装完 Xcode 就立刻下运行时，别等写代码时才发现。

4、首次构建卡在 "Downloading gradle-x.x"

• 现象：npm run android长时间停在下载 Gradle 发行版（一百多 MB）。

• 原因：默认从services.gradle.org（国外）下载。

• 解法：改android/gradle/wrapper/gradle-wrapper.properties的distributionUrl为腾讯镜像（步骤 7）。只影响"Gradle 本体"这一次下载；后续构建用的 Maven 依赖（google()/mavenCentral()）国内一般能直连，真慢再往android/build.gradle的 repositories 里加阿里云源。

5、App 装上了，Metro 却没起来（CLI 不吭声地失败了）

• 现象：构建安装成功，但 App 红屏/白屏报 "Unable to load script"；日志里其实有一句error Cannot start server in new windows because no terminal app was specified。

• 原因：npm run android正常会顺手帮你开一个新终端窗口跑 Metro，但在某些终端环境（无 Terminal.app 关联、脚本化执行）下这一步静默失败，又不妨碍继续构建，于是装了个"没有粮食的 App"。

• 解法：养成习惯——Metro 自己开终端跑，别依赖 CLI 自动拉起：

npm start

验证：curl http://localhost:8081/status→packager-status:running。

• 认知：Debug 包 = 空壳，JS 代码由 Metro 实时下发。Metro 没跑，App 必然报错。报错信息里那句 "Make sure you're running Metro" 说的是真的。

6、权限弹窗每次启动都来捣乱

• 现象：App 刚起就弹「允许查找并连接到附近设备？」，点掉一次下次还弹；更烦的是弹窗期间 App 根本不继续加载 bundle，容易被误判成"App 坏了"。

• 原因：RN 新版模板依赖带的蓝牙权限（BLUETOOTH_SCAN）在 Android 12+ 是运行时权限；没做选择前每次启动都问。

• 解法：测试项目直接永久授权/拒绝：

adb shell pm grant com.myapp android.permission.BLUETOOTH_SCAN

• 方法论：排查"App 界面不对"时，先确认没有系统弹窗挡在前面：

adb shell dumpsys window | grep mCurrentFocus # 焦点在 com.myapp/.MainActivity 上 = 没有弹窗挡道 # 焦点在 permissioncontroller 上 = 有权限弹窗

7、Android 16 上 App 死活连不上 Metro——全网新坑，静默无报错（压轴）

这是本次搭建耗时最长的坑，完整还原排查过程，因为这个过程本身就是方法论。

现象：

• 构建安装全成功，Metro 在跑，但 App 永远红屏报 "Unable to load script"

• App 日志：ReactHost.isMetroRunning(): Async result = false——每次探测 6 秒超时

• 最迷惑的点：进模拟器 shell 手动测网络完全通：

adb shell 'printf "GET /status HTTP/1.1\r\nHost: 10.0.2.2:8081\r\n\r\n" | nc -w 5 10.0.2.2 8081' # 返回 HTTP/1.1 200 OK ← 网络明明是好的！

背景知识：10.0.2.2是 Android 模拟器访问"宿主机（你的 Mac）"的专用别名地址。App 连 Metro 走的就是它。

逐一排除的嫌疑（都排除了，这个清单就是你的排查模板）：

1. Metro 活着吗？→curl localhost:8081/status✅ 通

2. Metro 监听地址对吗？→lsof -iTCP:8081显示tcp46 *.8081（IPv4/IPv6 双栈）✅

3. 模拟器路由对吗？→adb shell ip route标准 10.0.2.0/24 ✅

4. Mac 防火墙拦了？→ 系统设置里防火墙关闭 ✅

5. Metro 的 Host 头校验拒绝？→ 手动带Host: 10.0.2.2:8081请求，200 ✅

6. 模拟器系统代理脏了？→adb shell settings get global http_proxy= null ✅

7. App 没有网络权限？→aapt2 dump permissions app.apk，INTERNET 在 ✅

8. Android 禁明文 HTTP？→ APK 清单usesCleartextTraffic=true✅

真凶：查 App 的权限授予状态时发现：

adb shell dumpsys package com.myapp | grep ACCESS_LOCAL_NETWORK # android.permission.ACCESS_LOCAL_NETWORK: granted=false

Android 16（API 36+）新增了「本地网络访问」权限ACCESS_LOCAL_NETWORK。系统把访问10.0.2.2（本地/局域网地址）列为受保护行为，未授权的 App 访问会被静默丢弃（无报错、无弹窗、表现为超时）——而 shell 里的 nc 是系统进程不受限。这就是"shell 通、App 不通"的完美解释。

解法（一条命令）：

adb shell appops set com.myapp ACCESS_LOCAL_NETWORK allow

执行后重启 App，实测 1.2 秒连上 Metro（对比之前 6 秒超时），bundle 秒加载，欢迎页渲染。

⚠️ 重要：

• 每装一个新 App（新包名/重装）都要重新执行一次，这是 per-app 设置

• 用 Android 15 及以下模拟器的同学遇不到这个坑，但新机器新建 AVD 默认就是新 API

• 未来 RN 官方模板大概率会适配（自动声明/请求该权限），但 0.88 实测需要手动

8、首次构建 20 多分钟，是不是卡死了？

• 现象：npm run android后日志停在某个 Task 上很久不动，风扇狂转。

• 原因：首次构建要：下载 Gradle 本体（148MB）→ 编译 RN 的 Gradle 插件（Kotlin）→自动下载安装 NDK（约 600MB）、CMake、新版本 Build-Tools→ 编译四套 CPU 架构的 C++ 代码（arm64-v8a / armeabi-v7a / x86 / x86_64）→ 打包安装。实测全程 21 分钟（M 系芯片）。

• 判断死没死的方法：新开终端看构建进程 CPU

ps aux | grep -i gradle | grep -v grep # CPU 不为 0 = 还在干活

• 好消息：只有第一次这样。之后的热构建是秒级~分钟级（增量编译）。
• 别学我：等待期间不要Ctrl+C，中断后续传没问题但白等；更不要清缓存重来。

9、后台进程莫名消失 / 终端一关全没了

• 现象：模拟器跑着跑着自己关了；Metro、模拟器随终端关闭一起死。

• 原因：命令默认是终端的"子进程"，终端关/会话超时，子进程陪葬。

• 解法：需要长驻的进程用 nohup 挂后台：

nohup npm start > /tmp/metro.log 2>&1 & nohup emulator -avd 你的AVD名 > /tmp/emulator.log 2>&1 &

日常开发更简单：每个东西留一个专用终端窗口开着就行（Metro 一个、模拟器一个、构建一个）。

四、卡点速查表

五、日常开发工作流

环境搭建好后，每天开发只需三步（可全用GUI，不碰命令行）

1. 开模拟器：Android Studio ▶ 或 Xcode Simulator（iOS 免这步，run-ios 自动拉起）
2. 起 Metro：项目目录 npm start（专属终端，别关；iOS/Android 共用这一个）
3. 装代码：npm run android / npm run ios（App 已装时直接在模拟器点开即可）

改代码⌘S保存 → 模拟器秒级热更新（Fast Refresh）。Mac 和模拟器同机，iOS 侧网络天然通；Android 模拟器只要授权过 ACCESS_LOCAL_NETWORK 就一劳永逸（重装 App 才要再来一次）。

常用调试命令：

adb logcat -s ReactNativeJS # 只看 RN 的 console.log（排查 JS 层问题第一现场） adb shell am force-stop com.myapp && adb shell am start -n com.myapp/.MainActivity # 重启 App

附录A：~/.zshrc环境变量汇总

# Homebrew 国内镜像（中科大） export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api" export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles" # JDK 17（brew openjdk@17） export JAVA_HOME="/opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home" export PATH="$JAVA_HOME/bin:$PATH" # Android SDK（React Native） export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools"

npm 镜像（不进 zshrc，存在 npm 自己的配置里）：

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

Gradle 镜像（每个新项目都要改一次）：android/gradle/wrapper/gradle-wrapper.properties→mirrors.cloud.tencent.com/gradle

附录 B：最终版本清单(以本机为例)

一句话总结：镜像三件套（brew 中科大 / npm 淘宝 / Gradle 腾讯）解决 90% 的"慢"；formula 优先于 cask解决装 JDK；Metro 自己起、别信自动；Android 16 模拟器连不上 Metro 就appops set ACCESS_LOCAL_NETWORK allow。其余的，交给耐心。