1.2 开发环境搭建
文档摘要
1.2 开发环境搭建 本节摘要：React 开发环境的核心是 Node.js 与包管理器，再加一个脚手架把构建管线配好。本节比较 Create React App 与 Vite 两条主路——CRA 零配置但封装深、构建慢，Vite 冷启动快、配置透明——并给出可复现的命令序列与目录结构解读，让你 10 分钟内跑起第一个 React 应用。 本节目标 阅读完本节，你应当能够： 检查 Node.
1.2 开发环境搭建
本节摘要：React 开发环境的核心是 Node.js 与包管理器，再加一个脚手架把构建管线配好。本节比较 Create React App 与 Vite 两条主路——CRA 零配置但封装深、构建慢，Vite 冷启动快、配置透明——并给出可复现的命令序列与目录结构解读，让你 10 分钟内跑起第一个 React 应用。
本节目标
阅读完本节，你应当能够：
- 检查 Node.js 与 npm 版本，判断环境是否就绪
- 分别用 Create React App 和 Vite 创建 React 项目并启动开发服务器
- 解读两种脚手架生成的项目目录结构
- 理解手动配置 Webpack 与 Babel 的利弊，知道自己是否需要走到那一步
一、问题与直觉：为什么搭环境这么烦
很多新手在「写第一行 React 代码」之前就放弃了，因为环境没搭起来。React 的代码不能直接在浏览器里跑——JSX 要编译、ES 模块要打包、开发服务器要热更新。这些事自己配一遍要碰 Webpack 配置、Babel 预设、各种 loader，光报错就能劝退一批人。
脚手架就是来解决这个问题的：把「编译、打包、热更新、代码检查」这些脏活预先配好，你拿到的是一个开箱即跑的项目骨架。
但这里有个重要的取舍要先说清楚：脚手架省了配置的麻烦，也藏了配置的真相。用 Create React App，你可能跑几个月都不知道 Babel 和 Webpack 是什么；换 Vite，你会更快接触到底层工具。两种选择没有对错，取决于你想「先跑起来」还是「边跑边懂」。
二、搭建前的准备：Node.js 与包管理器
先检查本机环境。打开终端，运行：
node -v npm -v
SOURCE 原文建议 Node.js 14 或更高版本。我建议直接上 LTS 版本——Node.js 的版本策略里 LTS 是长期支持版，稳定性最好，新项目优先选它，避免追新版本带来的兼容性坑。
包管理器除了 npm，还有 yarn 和 pnpm。yarn 以速度与锁文件著称，pnpm 以磁盘空间和依赖隔离见长。三选一即可，本教程示例以 npm 为主，命令格式大同小异——把 npm install 换成 yarn add 或 pnpm add，逻辑一致。
编辑器方面，VS Code 是目前 React 开发的主流选择，装上 ESLint 与 Prettier 插件就能获得补全、格式化、错误提示。选别的编辑器也行，但 VS Code 对 JSX、TSX 的支持成熟度最高，不折腾。
⚠️ 常见坑：版本不匹配。npm 装包报 peer dependency 冲突、脚手架要求更高版本的 Node，多半是 Node 太旧或太新。用
node -v确认版本，必要时用 nvm 这类版本管理工具切换。
三、路线一：Create React App——零配置但封装深
Create React App（CRA）是 Facebook 官方维护的脚手架，预配置了 Webpack 与 Babel，目标就是「零配置跑起来」。
创建与启动
npx create-react-app my-app cd my-app npm start
npx 会临时拉取 create-react-app 并执行，不需要全局安装。浏览器会自动打开本机的开发地址（默认 3000 端口），看到 React 欢迎页就说明环境通了。改一下 App.js 里的内容保存，页面热更新即时生效——这个「改完即见」的开发体验，就是开发服务器加热更新的功劳。
目录结构解读
my-app/ public/ # 静态资源，index.html 在这里 src/ # React 源码 App.js # 根组件 index.js # 入口文件，挂载 App index.css # 全局样式 package.json # 依赖与脚本
入口的链路值得理清：index.html 里有一个根节点，index.js 通过 ReactDOM 把 App 组件渲染进那个节点。SOURCE 原文对这条链路的注释很清楚——index.js 是 JavaScript 入口，App.js 是根组件。后面所有项目，无论脚手架怎么换，这条「入口 → 根组件」的骨架不变。
CRA 的取舍
| 优点 | 代价 |
|---|---|
| 零配置，适合快速起步 | 高度封装，自定义要 eject |
| 官方维护，文档完善 | 构建慢，Webpack 全量打包 |
| 标准化结构，团队协作容易 | 对新技术的跟进滞后 |
eject 是一个不可逆操作：执行后脚手架把内部配置全部吐出来给你，从此自己维护。多数项目不需要走到这一步——想自定义配置，更聪明的做法是选 Vite 或其他可配置脚手架，而不是把 CRA 拆开。
四、路线二：Vite——快，且透明
Vite 是 Vue 作者尤雨溪开发的新一代构建工具，如今已是 React 社区的主流选择。它的核心思路是「开发时用浏览器原生 ES 模块，不打包；构建时用 Rollup」。
创建与启动
npm create vite my-vite-app -- --template react cd my-vite-app npm install npm run dev
相比 CRA，Vite 的流程多一步 npm install——CRA 在创建时自动装了依赖，Vite 把这一步留给你，更可控。启动后终端会打印访问地址（默认 5173），浏览器打开即是欢迎页。
Vite 快在哪
传统的 Webpack 开发服务器要把整个项目的依赖都打包好再响应请求，项目一大，冷启动要等十几秒甚至更久。Vite 利用浏览器原生 ES 模块支持，按需编译——浏览器请求哪个模块，Vite 才编译哪个模块。冷启动自然快，改代码的热更新也快。SOURCE 原文用「闪电般的冷启动速度」形容，不夸张。
目录结构上，Vite 和 CRA 的骨架几乎一样，多了一个 vite.config.js 配置文件。入口文件是 main.jsx 而非 index.js，逻辑相同：main.jsx 把根组件渲染到 index.html 的根节点。
| 维度 | CRA | Vite |
|---|---|---|
| 冷启动 | 慢（全量打包） | 快（按需编译） |
| 配置自由度 | 低，eject 才能改 | 高，vite.config.js 直接改 |
| 技术跟进 | 偏滞后 | 快 |
| 生态 | 成熟稳定 | 活跃但部分插件待完善 |
| 适合场景 | 快速原型、教学 | 中大型项目、新项目 |
💡 关键直觉：2026 年的现在，新项目直接上 Vite，不用犹豫。CRA 的价值在于教学和存量项目，它不是「未来」。这句话五年后可能又变了，但选型逻辑不变：看构建速度、配置自由度、维护活跃度。
五、路线三：手动配置 Webpack 与 Babel
要不要了解手动配置？我的判断是：不必自己配，但必须知道里面有什么。
手动配置的流程大致是：初始化 package.json，安装 react、react-dom、webpack、babel-loader、@babel/preset-env、@babel/preset-react 等依赖，写 webpack.config.js 配置 entry 与 output，再用 HtmlWebpackPlugin 生成 HTML。SOURCE 原文完整给出了这一串命令和配置文件，值得读一遍——读完你就知道 CRA 和 Vite 替你做掉了多少事。
核心配置可以浓缩成四件事：入口（entry）告诉 Webpack 从哪个文件开始；出口（output）告诉它把打包结果放哪、叫什么；loader 告诉它遇到 .jsx 文件怎么处理（交给 babel-loader 转译）；插件（plugin）负责 HtmlWebpackPlugin 这类额外工作。理解这四个概念，构建配置就不再神秘，而是一个「告诉工具如何处理文件」的过程。
但真要自己搭，除非是在做构建工具相关的底层工作，否则不推荐。构建配置是工程问题的次要部分，业务代码才是主战场。把这些时间留给 React 本身的学习更划算。
这条链就是所有脚手架背后的共同逻辑：JSX 转译成标准 JavaScript，Webpack 或 Rollup 打包成浏览器可用的资源。无论你用哪个脚手架，认识这条链，遇到构建报错就不会两眼一抹黑。
六、搭建后的验收清单
环境「跑起来」不等于环境「是对的」。启动第一个项目后，花一分钟做三件事验收：如果这一步缺了，后面写的代码全是在一个没验证过的地基上盖房子，出了问题分不清是代码错还是环境错。
第一，在页面源码里找到根节点挂载点。浏览器打开页面按 F12 看 Elements，你应该能看到 index.html 里的根节点内部被 React 渲染的内容塞满了。如果根节点是空的，说明组件没渲染上去，多半是入口文件里挂载的节点 id 和 HTML 里的对不上——这是初学者最常见的「白屏」原因。
第二，改一行代码保存，看热更新是否生效。改 App 组件里的一段文字，保存后页面应无刷新更新。如果每次改动都整页刷新，说明热更新配置有问题，要检查是否用了受支持的项目结构。这一项过不过，直接决定后续开发体验是流畅还是难受。
第三，看终端有没有报错或警告。React 开发模式下对缺失 key、无效 DOM 属性会打警告，别无视——这些警告在排查问题时是金线索。同时留意终端里是否有编译错误堆栈，它通常比浏览器控制台的报错更靠近问题源头。
SOURCE 原文在 CRA 部分特别演示了修改 App.js 后浏览器自动刷新的行为，Vite 部分则强调 HMR（热模块替换）。这两者都被初学者当作「理所当然」，其实背后是构建工具在帮你盯着文件变化，编译后推送更新。理解这一点，遇到「改了没反应」就知道该检查什么：文件保存了没有、终端有没有编译错误、浏览器控制台有没有报错。
| 验收项 | 方法 | 通过标准 |
|---|---|---|
| 挂载成功 | F12 看 Elements | 根节点内部有渲染内容 |
| 热更新 | 改代码保存 | 页面无刷新更新 |
| 无报错 | 看终端与控制台 | 无红色错误、无关键警告 |
常见报错与排查
环境搭建阶段的高频报错就那么几类，提前知道怎么查，能省大量时间：
| 报错特征 | 根因 | 处理 |
|---|---|---|
| command not found | Node 没装或没进 PATH | 重装 Node 并重启终端 |
| 依赖版本冲突 | Node 太旧或太新 | 升级到 LTS，或降级依赖 |
| 端口被占用 | 3000/5173 被其他程序占用 | 换端口或关掉占用进程 |
| 根节点渲染为空 | 挂载节点 id 不匹配 | 检查入口文件与 HTML 的 id |
| 热更新失效 | 项目结构不规范 | 检查文件是否在受监控目录内 |
排查的通用顺序记一个口诀：先看终端编译输出，再看浏览器控制台，最后才怀疑配置。大多数报错在第一步就能看到明确提示，别急着翻配置文件。
七、怎么选：一张决策清单
| 你的情况 | 推荐 |
|---|---|
| 刚学 React，想最快跑起来 | Vite |
| 维护存量 CRA 项目 | 保持 CRA，别急着迁移 |
| 学习构建原理 | 手动配一次 Webpack，然后删掉 |
| 公司统一规范 | 按团队基建选，通常已定 |
💡 关键直觉：搭建环境的本质是「让工具链替你干活」。评价一个脚手架，别只看它启动快不快，要看它在你遇到问题时，是把你往配置深处带，还是给你一个能看懂的入口。Vite 的优势恰恰在后者。
⚠️ 常见坑：多个人协作时环境不一致。有人 Node 16、有人 Node 20，同一个项目跑出不同结果。项目里放一个 .nvmrc 或 engines 字段固定 Node 版本，比在群里反复解释「我这边是好的」有效得多。
关于 pnpm 的一点补充
如果团队已经用了 pnpm，别为了本教程特意换回 npm。pnpm 的依赖安装速度和磁盘占用在大型项目里有明显优势，而它对 React 项目毫无影响——React 本身不关心你用哪个包管理器。唯一要注意的是，如果遇到 peer dependency 报错，可以先检查是不是 pnpm 的严格模式在起作用，必要时在 .npmrc 里调整配置。工具是服务项目的，别反过来被工具绑架。
一节小结
- 环境三件套：Node.js（LTS）、包管理器（npm/yarn/pnpm）、编辑器（推荐 VS Code）
- CRA：零配置、官方维护，但封装深、构建慢、自定义需 eject
- Vite：按需编译冷启动快，配置透明，新项目首选
- 共同骨架：入口文件 → 根组件 → 渲染进 index.html 根节点
- 构建链条：JSX 经 Babel 转译、经 Webpack/Rollup 打包
- Webpack 四要素：entry、output、loader、plugin
- 验收三件事：挂载成功、热更新生效、无报错
- 报错排查顺序：先终端、再控制台、后配置
- 选型逻辑：看构建速度、配置自由度、维护活跃度，不盲从
- 团队一致：用 .nvmrc 或 engines 固定 Node 版本，避免环境漂移
环境跑通了，下一节进入 JSX——写代码时你将第一次和「类 HTML 却不是 HTML」的语法打交道，先弄清楚它的编译真相，后面少踩一半坑。