1.3 环境搭建与项目初始化

1.3 环境搭建与项目初始化

本节摘要：环境搭建是 RN 学习曲线里最陡的一段——不是因为它难，而是因为它把 Node 工具链、iOS 工具链、Android 工具链三套体系压进了同一个下午。本节先帮你选对初始化路线（Expo 或裸 CLI），再按双端分层拆解安装步骤，最后把装机路上最常见的报错逐个排掉。完成后你将拥有一个在 iOS 与 Android 上都能跑起来的空项目，全册后续所有动手环节都建立在它之上。

一台新电脑到双端跑通之间隔着什么

选型定案之后，落地第一个动作是把环境立起来。先把两条初始化路线的差异说透，这一步选错，后面的体验会完全不同。Expo 路线把原生工程抽象掉了：你几乎只写 JavaScript，扫码即可在真机预览，构建与打包交给云端完成，代价是原生模块的自由度受限——不过随着配置插件机制的成熟，绝大多数原生需求如今也能在 Expo 项目里满足。裸 CLI 路线（社区命令行工具初始化）直接生成完整的 iOS 与 Android 原生工程，原生目录就躺在你眼前，想改什么改什么，代价是环境依赖全要自己管理。我的建议按场景分：纯 JS 业务应用、团队没有原生工程师、追求最快上手，选 Expo；要深度定制原生模块、接老的原生工程、或第 7 章的重度桥接玩法，选裸 CLI。全册示例两种路线都兼容，涉及差异时会注明。

图：三套工具链的分层关系

安装步骤：按层推进，装完一层验一层

第一层是共享 JS 工具链。安装 Node.js 的长期支持版本，用包管理器自带版本管理工具的读者直接切到活跃支持线即可。装完在终端执行版本查看命令确认输出正常。macOS 用户建议顺手装好 Watchman，它是文件变更监听服务，Metro 热刷新依赖它，缺了它热刷新会变得迟钝甚至失灵。

第二层按平台分叉。iOS 侧只有一条路：从应用商店装 Xcode，首次启动时在设置里补装命令行工具与目标版本的模拟器；再用 Ruby 的包管理器装 CocoaPods，它是 iOS 原生依赖的管理器，裸 CLI 项目安装原生依赖时必然经过它，版本过旧是常见故障源。Android 侧在任何桌面系统都可行：装 Android Studio，首次启动向导里让它自动下载 SDK 与平台工具；关键一步是在 SDK 管理器里确认目标 API 平台与构建工具已就位，并接受许可证协议——许可证没接受是初始化后构建报错的第一大来源。还需要一个 JDK，现在的构建插件对版本有明确要求，跟着 RN 官方环境指南给的版本走最稳。最后配置环境变量，把平台工具目录加进系统路径，让终端能直接调用 adb 等命令。

初始化与首次运行：命令行会话实录

环境就绪后，初始化只要几条命令。下面是裸 CLI 路线的完整会话，注释解释每步在做什么：

# 初始化项目：生成 App.tsx、ios 与 android 目录及全部配置
npx @react-native-community/cli@latest init RnBloom --skip-install

cd RnBloom
npm install

# iOS：安装原生依赖（首次必跑，原生依赖变更后也要跑）
cd ios && pod install && cd ..

# 启动 Metro 开发服务器（保持这个终端窗口常驻）
npm start

# 另开终端：启动 iOS 模拟器构建（仅 macOS）
npm run ios

# 另开终端：启动 Android 构建与安装（需已启动模拟器或连接真机）
npm run android
​

Expo 路线更短：用脚手架命令创建项目后直接执行启动命令，终端会出现二维码，手机装 Expo Go 应用扫码即可预览，模拟器调试则在启动命令后跟对应平台参数。两个路线共同的「心跳」是 Metro：它是 RN 的开发服务器与打包器，负责把 JS 代码实时编译并推到设备上。热刷新没反应、报「无法连接开发服务器」时，第一反应永远是检查 Metro 窗口还活着没有、设备与电脑是否在同一网络。

首次运行是报错高发段，把出镜率最高的几类列在这里。构建阶段报许可证未接受：回到 SDK 管理器把许可证逐项接受。报找不到 SDK 或平台工具：环境变量没配对，用诊断命令核对路径。iOS 侧报 Pods 相关错误：多数是 CocoaPods 版本或 Ruby 环境问题，升级后再跑安装。模拟器白屏转圈：九成是 Metro 连不上，检查端口占用与网络。这些报错的共性是「信息吓人、病因简单」，先对号入座再动手，别急着重装一切。

完整案例：新人装机全记录

背景：团队来了名前端背景的新同事，用一台全新 MacBook 走裸 CLI 路线，目标是当天在双端跑通空项目。过程记录如下：Node 与 Watchman 顺利就位；Xcode 安装耗时最长，期间并行装 Android Studio；初始化项目成功，但 iOS 构建在 Pods 安装处报错，原因是系统自带 Ruby 版本过旧，用版本管理器装新版 Ruby 并重装 CocoaPods 后通过；Android 构建报许可证未接受，接受后模拟器亮屏成功；最后真机联调，Android 真机开了开发者模式与调试授权后 adb 正常识别，iOS 真机需要在 Xcode 里信任开发者证书。结果：约半天的有效工时完成双端跑通，其中等待 Xcode 下载的时间占了小半。解读与变式：装机耗时的大头是下载与编译等待，不是智力活；如果团队规模化装机，把「新机初始化清单」写成内部文档，能把这个半天压缩到两小时。Windows 用户流程几乎一致，只是没有 iOS 那一层——这也再次印证了上一张分层图的判断：Android 工具链是全平台通用土壤，iOS 工具链被 Apple 锁在自家系统上。

版本管理与团队协作的两句提醒

环境之后、写代码之前，还有两句提醒值回票价。其一，Node 与原生工具链的版本要在团队内锁死：不同 Node 大版本编出的依赖树可能不同，谁的环境「能跑」没有意义，CI 与所有人的本地一致才有意义——仓库里放一份工具版本说明，新人装机按单抓药。其二，双端工程目录要不要进版本库：裸 CLI 项目建议把双端原生工程一并入库（虽带来一些冲突面，但换来了可追溯的配置历史），Expo 项目的托管原生层则按其约定处理。团队规模越大，这些约定的价值越大——环境差异是「我这明明是好的」类事故的第一来源。

本节要点回顾

• 路线决定体验：Expo 藏起原生工程换取轻快，裸 CLI 给全自由换全责任，按团队结构选；
• 按层安装按层验证：JS 工具链、iOS 工具链、Android 工具链三层各自独立出问题，逐层排查效率最高；
• Metro 是双端共同的心跳：热刷新失灵先查 Metro 与网络，再查别的；
• 报错对号入座：许可证、环境变量、Pods 版本、端口占用四大高频病因各有固定解法；
• 真机比模拟器更诚实：条件允许就尽早连真机，两端差异在真机上才暴露得充分。

土壤已经备好，种子即将下地。下一章拆开引擎盖，看这份 React 代码在双端的引擎舱里如何被点火、驱动、上路。