要点
React 环境搭建一句话说清：React 本身只是个 UI 库（library），不是全家桶框架，官方早就不提供统一脚手架——你要做的是一次组合：Vite 负责开发服务器与构建，ESLint 负责正确性检查（尤其是 Hooks 规则），Prettier 负责格式，React DevTools 负责调试。三条起步路线（Vite 单页、Next.js 全栈、在线 playground）按”服务端在不在场”选，不按”越全越好”选。
为什么不再有官方脚手架
2025 年 2 月 14 日，React 团队在官方博客发文《Sunsetting Create React App》，正式宣告 create-react-app 退役：不再收新特性，也不再作为新项目的推荐入口。官方文档《Creating a React App》现在只给两条路：要么直接用框架（Next.js、React Router、Expo 等），要么用 Vite 这类构建工具自建。原因也简单：CRA 把构建链锁死在 react-scripts 这个黑盒里，而生态早已转向可组合的工具。
这条事实决定了一个认知：React 的”环境搭建”永远是在选组合，不是装一个包。旧教程里 npx create-react-app、npm run eject、改 webpack.config.js 那一套，全部属于历史，识别到这些特征就可以换教程了。
三条起步路线对比
| 路线 | 得到什么 | 适合 | 另外两个场景为什么不用它 |
|---|---|---|---|
| 在线 playground | 浏览器里直接写组件，零安装 | 学前摸感觉、验证单个概念 | 没有本地工程与锁文件，写不了多文件应用，学不了一周以上 |
| Vite + React（本系列主线） | 本地工程、锁文件、热更新（HMR） | 单页应用、小工具、系统学 React | 没有服务端渲染与文件路由，要 SEO 的产品会补得很辛苦 |
| Next.js 全栈框架 | 路由、渲染策略、API 层一体化 | 内容站、需要 SEO 的真实产品 | 服务端组件、缓存语义会一起砸下来，第一周学语法时概念过载 |
判断依据只有一条：服务端在不在场。纯浏览器里跑的界面用 Vite 就够；页面要被搜索引擎收录、要服务端取数，第一站就该是框架。本系列前五篇都在 Vite 上，学完在路线篇再分岔。
系统要求
地基是 Node.js。当前 Vite 主线 7.x 要求 Node 20.19+ 或 22.12+（低于它安装或启动直接报错），操作系统不限，浏览器用当前版 Chrome 或 Firefox。先验证：
node --version # 需要 v20.19+ 或 v22.12+
npm --version不满足就升级：Windows 用 winget install OpenJS.NodeJS.LTS，macOS 用 brew install node@22；多项目共存不同 Node 版本用 nvm（Windows 用 nvm-windows），装完重开终端再验证一次。
路线一：Vite 建项（主线）
npm create vite@latest my-react-app
1. 交互菜单先选 React，再选变体：
1. JavaScript / TypeScript / TypeScript + SWC / TypeScript + React Compiler
1. 非交互等价写法（npm 7+ 必须用 -- 把参数递给 create-vite）：
1. npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install # create-vite 只生成骨架不装依赖，这步必须自己来
npm run dev变体怎么选：学习期用 JavaScript 或 TypeScript 都行，本系列示例两种读法通用；SWC 变体把 Babel 换成 Rust 写的 SWC，转译更快；React Compiler 变体内置编译器插件（当前为 RC 阶段，已可在新项目试用，自动完成大部分手动 memoization）。建议第一个月先不选 Compiler 变体——先理解手动 useMemo/useCallback 解决什么，再让编译器替你做，否则优化永远是一门玄学。
npm run dev 起的是 Vite 开发服务器，默认地址 http://localhost:5173，保存即热更新。目录速读：
my-react-app/
1. ├── index.html 入口页在根目录——Vite 工程的特征，开发时也允许直接改它
1. ├── vite.config.js Vite 配置：插件、代理、构建选项
1. ├── package.json scripts: dev / build / preview
1. ├── eslint.config.js ESLint 9 平坦配置（flat config）
1. └── src/
1. ├── main.jsx 入口：createRoot(...).render(<App />)
1. └── App.jsx 根组件，后续练习都从这里开始与 create-next-app 的显著差异：入口 HTML 由你持有，构建产物在 dist/，npm run preview 可本地预览构建结果——发布前务必跑一次，开发模式正常、构建后白屏的问题只有这一步能提前暴露。
路线二：Next.js 全栈
如果你的目标就是做内容站或需要 SEO 的产品，直接从框架开始：
npx create-next-app@latest my-app # 选项含义见站内同结构教程站内《Next.js 环境搭建与工具链》与本篇同结构，两相对照能看清”框架接管了什么”。React 基础在哪条路线上学都是同一套——组件、JSX、Hooks 不因框架而变，这也是先在 Vite 上打基础再上框架的理由。
路线三：在线 playground
react.dev 官方文档每个示例自带可编辑沙盒，CodeSandbox、StackBlitz 还能直接开完整 Vite 工程。适合正式装环境之前先写两行 JSX 找手感，或者在没装环境机器上验证一个想法。它替代不了本地工程：没有锁文件、没有 ESLint，协作与持久化都无从谈起。
ESLint：正确性检查，不是风格偏好
React 工程的 ESLint 里最重要的一条不是格式，是 eslint-plugin-react-hooks 的两条规则：rules-of-hooks（Hook 只能在顶层调用——违反即 bug）与 exhaustive-deps（依赖数组完整性——漏依赖即陈旧值 bug）。当前插件主线 v6 默认平坦配置，并内置了可选的 React Compiler 驱动规则。
npm install -D eslint @eslint/js globals eslint-plugin-react-hooks// eslint.config.js（ESLint 9 平坦配置）
import js from '@eslint/js'
import globals from 'globals'
import reactHooks from 'eslint-plugin-react-hooks'
export default [
{ ignores: ['dist'] },
js.configs.recommended,
{
files: ['**/*.{js,jsx}'],
languageOptions: {
ecmaVersion: 2022,
globals: globals.browser,
parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
},
plugins: { 'react-hooks': reactHooks },
rules: reactHooks.configs['recommended-latest'].rules,
// 配置键名以插件 README 当前版本为准；核心是把两条 hooks 规则挂上 error
},
]分工划清楚：ESLint 管”代码有没有错”，Prettier 管”代码长什么样”，不要让 ESLint 去管格式——两套格式规则互相打架是老项目的经典债。
Prettier
{
"semi": true,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "es5",
"printWidth": 80
}装完编辑器扩展（Prettier 与 ESLint 各一个），勾上保存时格式化即可。.prettierignore 里记得排除 dist/ 与 node_modules/。VS Code 对 JSX 的语法支持是内置的，不需要额外扩展。
React DevTools
浏览器扩展商店搜 “React Developer Tools”（Chrome/Edge/Firefox 都有），装完打开你的应用，DevTools 里会多出两个面板：
| 面板 | 干什么用 | 什么时候开 |
|---|---|---|
| Components | 看组件树、每个组件当前的 props 与 state | 排查”这个组件拿到什么数据了” |
| Profiler | 录制一次交互，看哪些组件渲染了、各花多久 | 排查”为什么这么卡”——深入用法见渲染篇 |
扩展图标亮起表示当前页面是 React 开发构建；生产站点上它保持灰色。怎么用 Profiler 定位无效重渲染，是《React 渲染与重渲染》的主题，这里先装上备用。
日常命令
| 命令 | 作用 | 什么时候用 |
|---|---|---|
npm run dev |
开发服务器，带热更新 | 写代码时全程开着 |
npm run build |
生产构建，产物进 dist/ | 发布前验证一次，顺带产出部署物 |
npm run preview |
本地起服务器伺服 dist/ | 构建后本地过一遍再上传 |
npm run lint |
跑 ESLint | 提交前；hooks 规则警告当 error 对待 |
npm ci |
按锁文件原样重装依赖 | 依赖装坏、换机器、CI 环境 |
pnpm 与 yarn 只是换个命令名（pnpm dev / pnpm ci），行为等价。团队里统一包管理器比选哪个更重要——锁文件格式不同，混用会导致依赖解析各说各话。
常见问题
Q1: 旧教程让我跑 npx create-react-app，行吗
不行，它已于 2025 年 2 月退役，react-scripts 不再维护。新项目在 Vite 与框架里选；存量 CRA 项目的迁移，官方建议是迁到框架或 Vite。教程里出现 react-scripts、eject、webpack.config.js 定制，就按 CRA 时代文献对待。
Q2: npm run dev 报 Node 版本错误
node -v 对照 20.19+ / 22.12+。nvm 用户 nvm install 22 再 nvm use 22，重开终端。
Q3: 5173 端口被占
Vite 检测到占用会提示自动换端口，确认即可；也可显式指定 npm run dev -- --port 5174。
Q4: 依赖装得慢或失败
大陆网络先换镜像：npm config set registry https://registry.npmmirror.com。装到一半失败时，保留锁文件删 node_modules 用 npm ci 重装；不要删锁文件——那会把所有依赖重新解析一遍。
最佳实践
反模式一：照抄 CRA 时代教程。eject 出来的 webpack 配置、全局挂载的 Polyfills、react-scripts 的代理配置在新工程里全都不存在，报错会指向不存在的文件。
反模式二：建好工程第一天就装 Router、状态库、UI 组件库。学语法期每一层依赖都是一层噪音；本系列到实战篇为止，运行时依赖只有 react 和 react-dom。
建完工程立即 git 提交一次，包含锁文件。脚手架只是起点，之后每次依赖变化都应该能从提交历史里解释清楚。
检查清单
- node -v 满足 20.19+ / 22.12+
- npm create vite@latest 建好工程，说得出自己选的变体是什么
- npm run dev 打开 http://localhost:5173 看到欢迎页，改一行代码看到热更新
- ESLint 装好，故意在组件里写一个条件调用的 useState，确认 rules-of-hooks 报红
- React DevTools 扩展装好，Components 面板能看到 App 的 props
- npm run build 与 npm run preview 各跑通一次
- git 提交了 package.json 与锁文件
下一步
这一篇的产出是一个能启动、能构建、能 lint、能调试的最小 React 工程。下一篇《第一个 React 应用》在这个骨架里写一个待办清单，把组件、JSX、useState 的第一课一次走完；想直接做全栈产品的读者，回看上文路线二引用的《Next.js 环境搭建与工具链》；Profiler 与渲染机制的深水区，留给《React 渲染与重渲染》。
版本核实（撰写时检索，2025-07）：React 当前稳定版为 19.1.x（19.0 于 2024-12 GA）；create-react-app 已于 2025-02-14 官宣退役；React Compiler 处于 RC 阶段（2025-04 发布候选版）；Vite 当前主线 7.x（要求 Node 20.19+ / 22.12+）；eslint-plugin-react-hooks 主线 v6，默认平坦配置。安装命令一律不钉版本号，具体以官方文档与你的锁文件为准。