2.1 基础开发环境准备

2.1 基础开发环境准备

本节摘要：React Native 依赖 Node.js 与 npm/yarn，Flutter 依赖 Dart 与 Flutter SDK。本节讲清两套工具链的安装、PATH 配置、镜像源加速与环境自检方法，并解释"包管理器选定一个就别混用""别把 Flutter 装进需管理员权限的目录"等新手最常踩的坑。

核心问题

阅读完本节，你应当能够：

1. 独立安装 Node.js LTS 并用 node -v、npm -v 完成验证。
2. 配置 npm 与 yarn 的国内镜像源，理解其用途。
3. 正确解压 Flutter SDK、配置 PATH，并跑通 flutter doctor。
4. 说清"项目里 npm 与 yarn 不要混用"的原因。

一、问题与直觉

环境搭建最大的反直觉之处在于：装东西本身不难，难的是知道装完怎么验证、报错往哪个方向查。很多新手卡在"装好了但命令找不到""下载依赖慢到崩溃""版本对不上"这些环节，而这些大多不是技术难题，是方法问题。

先建立一张"工具清单"的直觉：React Native 这条路要的是 JavaScript 生态——Node.js 是运行时，npm 或 yarn 是包管理器，Metro 打包器负责把 JS 编译成设备能跑的包；Flutter 这条路要的是 Google 生态——Flutter SDK 一个压缩包就自带 Dart SDK、引擎和命令行工具，不用单独装 Dart。两套工具链并行存在，互不干扰，这正是本书"双框架对照"的常态。

二、核心原理

2.1 React Native 侧：Node.js 与包管理器

Node.js 是 JavaScript 的运行时环境，React Native 的打包工具和命令行工具都建立在它之上。推荐安装 LTS（长期支持）版本——稳定、安全更新周期长，适合开发与生产。

安装要点。Windows 和 macOS 直接下载官方安装包（.msi 或 .pkg），安装时确保勾选"Add to PATH"，这样 node 与 npm 会被自动加入系统路径。Linux 上推荐用 nvm（Node 版本管理器），方便在多个 Node 版本间切换——不同项目对 Node 版本要求不同，nvm 是处理这种分歧的标准工具。

验证命令。装完后开个新终端：

node -v
npm -v
​

两个命令都返回版本号，说明安装成功。如果提示"command not found"，先去检查 PATH 是否真的配好了，而不是重装一遍。

包管理器之争。npm 随 Node.js 自带，yarn 是 Facebook 等团队联合开发的替代品。历史上 yarn 以安装速度和依赖版本一致性见长，但近年 npm 已经追上，性能差距很小。选哪个？答案是：在项目里选定一个并保持一致。混用会导致锁文件不一致、依赖版本错乱，凭空制造大量 bug。React Native 官方文档两种命令都给，你只要别今天 npm 装、明天 yarn 装就行。

2.2 镜像源：国内下载加速的关键

npm 默认注册表在国外，国内下载依赖经常又慢又不稳定。解决办法是配置镜像源，把注册表指向国内节点：

npm config set registry https://registry.npmmirror.com/
npm config get registry   # 验证是否生效
​

yarn 同理：

yarn config set registry https://registry.npmmirror.com/
yarn config get registry
​

💡 关键直觉：镜像源只是"换个下载地址"，不影响包的内容与安全性。但它能实打实把一次 install 的时间从几十分钟压到几分钟。国内开发者装完 Node 的第一件事就应该是配镜像源。

2.2.1 npm 常用命令速记

新手阶段只需要记住几条高频命令，就能应付绝大多数场景：

npm install <包名>          # 安装一个包
npm install                # 按 package.json 安装全部依赖
npm install -g <包名>       # 全局安装，可在任意目录调用
npm uninstall <包名>        # 卸载
npm update <包名>           # 更新到兼容版本
​

-g 这个参数值得单独说：全局安装意味着这个工具属于"整个系统"，而不是某个项目。像 yarn 这种本身就是命令行工具的东西，全局安装合理；但项目依赖（UI 库、网络库）一定不要全局装，要装进项目自己的 node_modules，否则项目之间会互相污染版本。

2.2.2 yarn 出现的历史背景

yarn 由 Facebook、Google、Exponent 和 Tilde 联合推出，当年是为了解决 npm 的两大痛点：安装速度慢，以及同一份依赖在不同机器上装出的版本不一致。它引入了锁文件（yarn.lock）来固化依赖版本，安装过程并行化来提速。这些年 npm 通过 package-lock.json 和性能优化把差距基本抹平，yarn 的独家优势已不明显。因此现在的建议回归朴素：选一个用到底，团队的效率比工具之争重要。

2.3 Flutter 侧：Flutter SDK

Flutter SDK 是一个包含框架、Dart SDK、引擎与命令行工具的压缩包。安装分三步：

解压。下载对应系统的稳定版压缩包（Windows 是 zip，macOS 是 zip，Linux 是 tar.xz），解压到一个短路径且不含空格的目录。推荐 Windows 用 C:\src\flutter，macOS/Linux 用开发目录下的 flutter 文件夹。

关键禁忌：不要解压到需要管理员权限的目录（比如 C:\Program Files）。放在那里会导致后续命令频繁弹权限窗，写文件也会被系统拦截，是新手踩得最多的坑之一。

配 PATH。把 SDK 的 bin 目录加进系统环境变量：Windows 在"系统变量 > Path"里新建一条，填 C:\src\flutter\bin；macOS/Linux 在 shell 配置里加 export 语句再 source 生效。

自检。装完跑 flutter doctor，它会像体检报告一样列出环境还缺什么：

flutter doctor
​

它会检查 Flutter 自身、Android 工具链、iOS 工具链（macOS 上）、IDE 等，每一项给出状态和建议。首次运行可能下载依赖，属正常现象。

2.3.1 为什么不需要单独装 Dart

一个常见困惑是：Flutter 用 Dart 写，那我是不是还要单独装一个 Dart SDK？不需要。Flutter SDK 自带 Dart，你装的 flutter 命令背后就有完整的 Dart 工具链。单独装 Dart 只适用于"只想写纯 Dart 命令行脚本、不碰 Flutter"的场景。对本书读者来说，装一个 Flutter SDK 就同时拥有了 Dart。

2.3.2 flutter doctor 输出怎么读

flutter doctor 的输出不是给机器看的，是给你看的。每一行是一个检查项，状态符号的含义要先弄清楚：对勾表示该项就绪，感叹号表示有警告但不致命，叉号表示必须处理。初学者最容易犯的错是看到一堆感叹号就慌，实际上很多只是"检测到可选的改进项"，不影响基本运行。真正要盯着的是叉号，按它提示的修复步骤处理即可。跑完 doctor 后，常见的待处理项就是"未装 Android Studio""未配置 Xcode"这类平台环境问题——正好是本章后面几节的内容。

2.4 环境拓扑总览

这张图把两套工具链的"零件"和它们之间的关系画清了：RN 侧是 Node 加包管理器，Flutter 侧是一个 SDK 包全家桶，共同环节是环境自检与排错思路。

三、工程实践要点

3.1 安装方式速查

3.2 排错优先级清单

环境报错时，按这个顺序查，能省下大量瞎折腾的时间：

第一层：命令找不到。大概率是 PATH 没配好。检查系统环境变量里有没有对应 bin 目录，改完务必重开终端再试。

第二层：版本对不上。React Native 与 Flutter 对 Node、JDK 有版本要求，报错信息里通常会写明需要的最低版本。升级或降级到兼容区间即可。

第三层：下载超时或失败。优先检查镜像源是否配置，再考虑网络问题。

第四层：缓存陈旧。改完依赖后报"模块找不到"，多半是打包器缓存没刷新。清缓存或重启打包进程通常能解决。

3.2.1 环境变量改完不生效怎么办

这是一个高频到值得单独写一段的问题。症状：明明配好了 PATH，开终端执行命令还是提示找不到。原因往往不是配置错了，而是终端没有读到最新的环境变量。

解法按顺序试：先关掉当前终端、重开一个新的（多数情况这样就够了）；还不行，注销重新登录或重启系统（Windows 尤其如此）；都试过仍不行，再回到环境变量设置里检查是不是路径拼写错了、多打了空格或反斜杠。这个排错顺序能覆盖九成"配了不生效"的情况。别一上来就怀疑自己装错了重装一遍，浪费时间。

⚠️ 常见坑：安装 Flutter SDK 时顺手装进了 C:\Program Files。看起来只是"换个目录"的小事，实际会引发权限拦截、命令执行失败一系列连锁问题。正确做法是一开始就选一个用户可写、无空格的短路径。
💡 关键直觉：环境问题九成是 PATH、版本、镜像源这三件事。把这三样摸熟，后面几章几乎所有"跑不起来"都能自己定位。

3.3 环境是否就绪的自检口诀

工具装完别急着写代码，先做一遍完整的自检，把每一环的状态确认清楚。顺序是"由近及远、由验证到运行"：

node -v 与 npm -v     验证 Node 生态
yarn -v               （如果选 yarn）
flutter doctor        验证 Flutter 全家桶
flutter --version     确认 Flutter 版本号
​

每一环都通过了，环境才算真正就绪。很多项目报错的真相是"工具链装了一半"——node 有了但 yarn 没装，或者 Flutter SDK 解压了但 PATH 没配。自检口令就是帮你一次性把这几个漏洞堵上。养成这个习惯后，后面每一章开头都可以花十秒钟确认环境状态，而不是遇到报错才开始排查。

3.4 包管理器选择的一个现实视角

npm 与 yarn 之争常让新手纠结，其实还有一个更现实的角度：项目模板默认用哪个，就跟哪个。React Native 脚手架生成的工程自带 package-lock.json（npm 锁文件），你继续用 npm 就不会有任何额外配置；强行换 yarn 反而要处理锁文件不一致。Flutter 侧不存在这个选择——pub 是唯一包管理器。所以这个纠结本质上只在 RN 生态存在，而答案常常是"跟着模板走"。等到团队有明确偏好再统一切换，比入门阶段纠结更有意义。

3.5 关于 nvm 的补充说明

前面提到 Linux 上用 nvm 管理 Node 版本，这里补一句为什么推荐它：不同 RN 项目对 Node 版本的要求可能不同，nvm 允许你在同一台机器上随时切换版本。你只需要记住三条命令：nvm install 装指定版本、nvm use 切换版本、nvm alias default 设默认。Windows 用户可以用 nvm-windows 获得类似能力。当某个项目报"Node 版本不支持"时，nvm 就是你的版本切换开关，比卸载重装高效得多。

本章回顾

• 两套工具链：RN 用 Node 加 npm/yarn，Flutter 用 Flutter SDK 全家桶，互不干扰、并行存在。
• LTS 优先：Node.js 选 LTS 版本，稳定且安全更新周期长。
• 包管理器统一：项目内选定 npm 或 yarn 一个，混用会产生锁文件不一致的连锁问题。
• 镜像源加速：npm 与 yarn 都可配置国内镜像，装完第一件事就配。
• Flutter 路径：SDK 解压到短路径、无空格、无管理员权限的目录，再配 PATH。
• 自检优先：node -v、flutter doctor 是环境是否就绪的第一道验证。
• 排错顺序：命令找不到查 PATH，版本报错查兼容区间，下载慢查镜像源，缓存旧就清缓存。

FAQ：基础环境的高频问题

问：Node.js 一定要用 LTS 吗？能不能用最新版？ 建议 LTS。最新版虽然功能更新，但生态里的工具链（打包器、编译器）对新版本的适配总有滞后，容易出现"框架要求 Node 16，你却装了 20 不兼容"这类问题。LTS 版本是被大量项目验证过的稳定区间，够用且省心。

问：yarn 是不是已经被淘汰了？ 没有，它仍在活跃维护，只是 npm 的进步让它的差异化优势变小了。现在选择 yarn 更多是团队习惯或项目约定。核心原则不变：一个项目只用一个包管理器。另外提醒一句，网上很多旧教程推荐的 yarn 命令是全局安装的经典用法，项目内实际使用的是版本固定的 yarn，别混为一谈。

问：macOS 上能用 Homebrew 装这些工具吗？ 能。Homebrew 装 Node 很常见，Flutter 也有 Homebrew 安装方式。两种方式选一个即可，关键在于理解它装到了哪里、PATH 是怎么配的。用包管理器装的工具，卸载和升级会更方便，但路径通常不直观，排查问题时先确认当前用的是哪一份。

工具链就绪，下一节我们给编辑器装上"武器"——VS Code 与 Android Studio 的配置与插件，让写代码和跑模拟器进入正轨。