必须先安装Node.js和npm，否则npx等命令无法执行；下载LTS版本并勾选“Add to PATH”，在VSCode终端运行node -v和npm -v验证；推荐用npm create vite@latest创建React项目，安装依赖后运行npm run dev启动。
node 和 npm 必须先装好，否则后续所有命令都会报 command not found: npx 或 Cannot find module 'react' —— VSCode 本身不提供运行时，它只编辑、不执行。
确认 node 和 npm 已正确安装
这是最常被跳过的一步，但它是整个流程的基石。
- 去
nodejs.org下载 LTS 版本（不是 Current），安装时务必勾选 “Add to PATH” - 打开 VSCode 内置终端（
Ctrl+`或Cmd+`），运行：node -v和npm -v—— 必须看到类似v20.11.1和10.2.4的输出 - 别用 macOS 自带的
/usr/bin/node，它版本太老，且常因权限问题导致npm install失败或报EACCES - 如果报错
command not found: npx，说明 PATH 没生效，重启终端或 VSCode 再试
用 vite 创建 React 项目（推荐）
比起 create-react-app，vite 启动更快、TS 开箱即用、配置更轻量，且仍在积极维护。
- 在终端中运行：
npm create vite@latest my-react-app -- --template react - 进项目目录：
cd my-react-app - 安装依赖：
npm install（别跳过！否则npm run dev会报错找不到react） - 启动开发服务器：
npm run dev—— 默认访问http://localhost:5173 - 如果卡在 “fetching…” 或下载极慢，先换镜像源：
npm config set registry https://registry.npmmirror.com
VSCode 中打开并启用关键扩展
没有这些扩展，JSX 高亮错乱、自动补全失效、保存不格式化，写起来会明显“卡顿”。
- 必须装：
ESLint（校验 React 规则）、Prettier（格式化）、ES7+ React/Redux/GraphQL/React-Native snippets（快速输入rfc生成函数组件） - 可选但实用：
Path Intellisense（路径自动补全）、Auto Rename Tag（改 JSX 标签名时同步闭合标签） - 打开 VSCode 设置（
Ctrl+,），搜索format on save并开启；再搜索default formatter，设为Prettier - 在项目根目录加
jsconfig.json（非必需但推荐）：{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["src/*"] } }, "include": ["src"], "exclude": ["node_modules"] }—— 这能让路径导入提示更准，避免Cannot find module './components/Button'
常见报错与直接解法
很多问题其实就差一行命令或一个配置项，不用重装、不用查半天。
-
Module not found: Can't resolve 'react'：90% 是没运行npm install，或者误在父目录而非项目根目录下执行了npm run dev -
Failed to load plugin 'react' declared in '.eslintrc.cjs'：删掉node_modules和package-lock.json，再npm install - JSX 语法标红、无智能提示：确认已安装
ESLint扩展，并检查 VSCode 右下角语言模式是否为JavaScript React（不是JavaScript） -
npm start报错：Vite 项目用的是npm run dev，CRA 才用npm start—— 脚手架不同，命令不能混用
真正卡住人的，往往不是技术本身，而是 node -v 没输出、npm install 没执行、或者 VSCode 当前工作区没打开项目根目录。这些细节一漏，后面所有操作都像在修一台没插电的电脑。
