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

D_xw_

170人浏览 · 2026-11-01 11:19:27

D_xw_ · 2026-11-01 11:19:27 发布

本文的含金量：所有步骤与坑位均在 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 模拟器专属，终极卡点，见卡点⑦）

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 多分钟，是不是卡死了？

一、开工前的认知

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

组件	作用	安装方式	必装平台
Homebrew	Mac 的软件包管理器	官方脚本	Android / iOS
Node.js	运行 npm / Metro 打包器	brew	Android / iOS
Watchman	Facebook 的文件监听工具，热更新不丢文件	brew	Android / iOS
Xcode	iOS 编译器 + 模拟器 + 全套苹果工具链	App Store	iOS
iOS 模拟器运行时	模拟器里的“iOS操作系统" （约8G，独立组件！）	Xcode下载	iOS
Cocoapods	iOS 原生以来管理器（iOS 界的 npm）	brew	iOS
JDK 17	编译 Android 用的 Java 工具链	brew	Android
Android Studio	Android SDK 管理器 + 模拟器 + AVD 创建工具	官网下载	Android
Android SDK / NDK / CMake	Android 编译工具链（部分回构建时自动补装）	Studio	Android
Metro	RN 的 JS 打包器 + 调试服务器（项目依赖自带）	-	Android / iOS

双平台 = 两套完全对立的工具链。只先做一个平台完全可以(建议先 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 走的就是它。

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

Metro 活着吗？→ curl localhost:8081/status ✅ 通
Metro 监听地址对吗？→ lsof -iTCP:8081 显示 tcp46 *.8081（IPv4/IPv6 双栈）✅
模拟器路由对吗？→ adb shell ip route 标准 10.0.2.0/24 ✅
Mac 防火墙拦了？→ 系统设置里防火墙关闭 ✅
Metro 的 Host 头校验拒绝？→ 手动带 Host: 10.0.2.2:8081 请求，200 ✅
模拟器系统代理脏了？→ adb shell settings get global http_proxy = null ✅
App 没有网络权限？→ aapt2 dump permissions app.apk，INTERNET 在 ✅
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 一个、模拟器一个、构建一个）。

四、卡点速查表

现象	根因	解法命令
brew 下载几分钟不动	ghcr.io 慢	配 USTC 镜像变量（见步骤 1）后重跑
`--cask` 装包永远下不完	cask 走 GitHub Release	改用 formula 版 / 官网手动下载
pod: command not found	PATH 未生效	`source ~/.zshrc`，重开终端
xcrun: invalid active developer path	Xcode 目录未指定	sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
iOS 模拟器设备列表为空	缺运行时	xcodebuild -downloadPlatform iOS
adb: command not found	ANDROID_HOME 未配/未生效	步骤 5.4 + `source ~/.zshrc`
Android 模拟器卡成 PPT	Intel 装了 arm 镜像或反之	删 AVD 重建，选对架构
构建卡 "Downloading gradle"	gradle.org 慢	distributionUrl 换腾讯镜像
构建报 JDK 版本不对	JAVA_HOME 未配/版本错	步骤 5.1，`java -version` 应为 17
App 红屏 "Unable to load script"	Metro 没跑	`npm start`，验证 `/status`
App 连不上 Metro 但网络看着正常	Android 16 本地网络权限	adb shell appops set 包名 ACCESS_LOCAL_NETWORK allow
App 启动总弹"附近设备"权限	BLUETOOTH_SCAN 运行时权限	adb shell pm grant 包名 android.permission.BLUETOOTH_SCAN
真机（USB）连不上 Metro	缺端口反向代理	adb reverse tcp:8081 tcp:8081
Metro 端口被占	上个 Metro 没退干净	`lsof -ti:8081
改了代码模拟器没反应	Metro 没跑 / watchman 缺失	确认 Metro 活着；`brew install watchman`

五、日常开发工作流

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

开模拟器：Android Studio ▶ 或 Xcode Simulator（iOS 免这步，run-ios 自动拉起）
起 Metro：项目目录 npm start（专属终端，别关；iOS/Android 共用这一个）
装代码：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：最终版本清单(以本机为例)

组件	版本
机器	Apple Silicon Mac, macOS 26
Homebrew	6.0.15（中科大镜像）
Node / npm	v24.18.0（npmmirror 源）
Watchman	2026.10.26
Xcode / iOS 运行时	27.2 / iOS 27.2 (Ready)
CocoaPods	1.17.0（brew，自带 Ruby 4.0.9 隔离）
JDK	OpenJDK 17.0.21（brew formula 版）
Android SDK / 模拟器	platforms 37.0 / build-tools 36+37 / emulator 37.2 / NDK 27.1（构建时自动补装）
RN / React / Metro	0.88.1 / 19.3.0 / 0.87.2（Hermes 引擎 + Bridgeless 新架构默认开启）
首次 Android 构建	21 分 9 秒（83 个任务）

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

开源鸿蒙跨平台开发者社区

开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。

更多推荐

矩阵正则化在编译阶段的真实收益：三个大厂开源片段的重写与汇编对照

矩阵正则化在编译阶段显著提升性能：对百度brpc、字节跳动sonic-rs、华为OpenHarmony的三个百行级代码片段重写为查表式矩阵化结构后，指令数降为1/4~1/12，条件分支清零，代码体积缩小至1/9~1/13，实测热路径性能提升9%~33%。关闭编译器优化后，结果真实反映手写逻辑收益，验证了“并列选项查表优于分支”的核心法则。