React 脚手架（Create React App & Vite）

本文是一份从零基础到进阶的 React
脚手架使用手册，覆盖环境搭建、脚手架安装、项目结构、开发调试、状态管理、路由、接口请求、打包部署与常见报错解决。建议收藏。

一、React 脚手架是什么？

React 本身只是一个 UI 库，并不包含：

打包工具（如 webpack、vite）
本地开发服务器
代码热更新机制
Babel 转译 ES6+ 代码
TypeScript 支持
打包优化配置

所以需要脚手架：

提供项目模板
自动安装依赖
内置开发&构建配置
统一项目结构和规范

目前主流方式：

工具特点

Create React App 经典，功能稳定，配置偏重
Vite 速度极快、现代化推荐
Next.js React 全栈框架、SSR、SSG

本文重点：Create React App + Vite

二、环境准备

1. 安装 Node.js

2. 推荐安装包管理工具

可选其一：

1 2	npm install -g yarn npm install -g pnpm

三、使用 Create React App 创建项目

方式一：使用 npx（推荐）

1	npx create-react-app my-react-app

方式二：使用 yarn

1	yarn create react-app my-react-app

进入项目：

1	cd my-react-app

安装依赖（必要时）：

1	npm install

启动项目：

npm start

浏览器打开：

http://localhost:3000

四、Create React App 项目结构详解

my-react-app
├── node_modules              依赖包
├── public                    公共静态资源
│   ├── index.html            页面模板
├── src
│   ├── index.js              入口文件
│   ├── App.js                根组件
│   ├── App.css               全局样式
│   ├── reportWebVitals.js    性能监测
│   ├── setupTests.js         单元测试配置
├── package.json              依赖与脚本
└── README.md                 项目说明

📌 重点：React 真实挂载点

在 public/index.html 中：

1	<div id="root"></div>

React 在此节点渲染：

import ReactDOM from "react-dom/client";

const root = ReactDOM.createRoot(document.getElementById("root"));
root.render(<App />);

五、脚手架常用命令

命令作用

npm start 启动开发服务器
npm run build 生产环境打包
npm test 启动测试
npm run eject 暴露全部配置（不可逆）

⚠ eject 不可回退，请谨慎使用。

六、编写第一个组件

1. 创建组件

src/components/Hello.js

function Hello(props) {
  return <h2>Hello, {props.name}</h2>;
}

export default Hello;

2. 注册并使用

App.js

import Hello from './components/Hello';

function App() {
  return (
    <div>
      <Hello name="React" />
    </div>
  );
}

export default App;

七、React Router 路由配置

1	npm install react-router-dom

创建页面

pages/Home.js

1
2
3

export default function Home() {
  return <h1>首页</h1>;
}

pages/About.js

1
2
3

export default function About() {
  return <h1>关于我们</h1>;
}

配置路由

App.js

import { BrowserRouter, Routes, Route, Link } from "react-router-dom";
import Home from "./pages/Home";
import About from "./pages/About";

export default function App() {
  return (
    <BrowserRouter>
      <nav>
        <Link to="/">首页</Link>
        <Link to="/about">关于</Link>
      </nav>

      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </BrowserRouter>
  );
}

八、请求后端接口（Axios）

安装：

1	npm install axios

使用：

import axios from "axios";
import { useEffect, useState } from "react";

export default function UserList() {
  const [users, setUsers] = useState([]);

  useEffect(() => {
    axios.get("https://jsonplaceholder.typicode.com/users").then(res => {
      setUsers(res.data);
    });
  }, []);

  return (
    <ul>
      {users.map(u => (
        <li key={u.id}>{u.name}</li>
      ))}
    </ul>
  );
}

九、使用 Vite 创建 React 项目（现代推荐）

npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
npm run dev

访问：

http://localhost:5173

支持 TypeScript 模板

1	npm create vite@latest my-react-app -- --template react-ts

十、.env 环境变量配置

在项目根目录创建：

.env.development
.env.production

写入：

REACT_APP_API=https://api.example.com

在代码中使用：

1	process.env.REACT_APP_API

十一、打包部署

1. 打包

1	npm run build

输出目录：

build/

可部署到：

Nginx
Vercel
GitHub Pages
阿里云 OSS
Netlify

GitHub Pages 示例

1	npm install gh-pages --save-dev

package.json 添加：

"homepage": "https://yourname.github.io/my-react-app",
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

执行：

1	npm run deploy

十二、常见报错与解决方案

❌ Command not found: create-react-app

解决：

1	npm install -g create-react-app

❌ npm start 端口占用

1	PORT=3001 npm start

Windows:

1	set PORT=3001 && npm start

❌ 内存不足（大项目）

1	export NODE_OPTIONS=--max_old_space_size=4096