React 安装教程：用 Vite 创建 React 项目

要安装 React，就用 Vite 创建一个新项目：运行 npm create vite@latest my-app -- --template react，然后依次运行 cd my-app、npm install 和 npm run dev。在此之前需要先安装 Node.js。Vite 会帮你配置好 React、JSX 编译，以及一个保存时自动刷新页面的开发服务器。

开始学习时，这些都不是必需的。下面的编辑器直接在本页运行 React，它是 Vite 为你生成的 App.jsx 文件的简化版。

import { useState } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    return (
        <div style={{ textAlign: 'center' }}>
            <h1>Get started</h1>
            <p>
                Edit <code>src/App.jsx</code> and save to test <code>HMR</code>
            </p>
            <button type="button" onClick={() => setCount((count) => count + 1)}>
                Count is {count}
            </button>
        </div>
    );
}

点击按钮，然后修改标题文字：预览会随着你的输入更新，就像 Vite 的开发服务器不刷新页面就替换你改动的内容一样（这就是“HMR”，即模块热替换的含义）。

准备工作：Node.js

构建 React 应用的工具运行在 Node.js 上，npm（它的包管理器）会随 Node.js 一起安装。从 Node.js 官网或用 nvm 等版本管理工具安装当前的 LTS 版本，然后在终端中检查：

node -v
npm -v

两条命令都应该打印出版本号。如果 node -v 打印的版本较旧，请升级：Vite 8 需要 Node.js 20.19 或更高版本（22 系列需要 22.12 或更高），在更旧的版本上会打印警告。

用 Vite 创建 React 应用

在你存放项目的文件夹中运行这四条命令：

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

• npm create vite@latest 会下载最新的项目生成器。my-app 是文件夹名，--template react 选择使用 JavaScript 的普通 React 模板。多出来的 -- 让模板选项穿过 npm 传给生成器。
• npm install 会把 React、React DOM、Vite 以及 package.json 中列出的其他依赖下载到 node_modules 中。
• npm run dev 会启动开发服务器并打印一个本地地址，通常是 http://localhost:5173。在浏览器中打开它。

接着生成器会问两个问题：要配置哪个代码检查工具（Oxlint 还是 ESLint），以及是否现在就安装并启动应用。如果第二个问题回答是，它会替你运行 npm install 和 npm run dev，你就可以跳过最后两条命令。如果要用 TypeScript，请改用 --template react-ts，详见 React 与 TypeScript。

Vite 创建的文件

my-app/
├── index.html
├── package.json
├── vite.config.js
├── README.md
├── public/
└── src/
    ├── main.jsx
    ├── App.jsx
    ├── App.css
    ├── index.css
    └── assets/

其中最重要的有三个：

index.html 是浏览器加载的页面。它的 body 中只有一个空元素 <div id="root"></div>，以及一个加载 src/main.jsx 的 script 标签。React 会把整个应用绘制在这个 div 里。

src/main.jsx 是入口文件，它把 React 和页面连接起来：

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.jsx';

createRoot(document.getElementById('root')).render(
    <StrictMode>
        <App />
    </StrictMode>,
);

createRoot 接收 #root 元素，让 React 接管它内部的一切。render(<App />) 会在那里绘制你的顶层组件。StrictMode 是开发辅助工具，会做一些额外检查，在生产构建中不起作用（见 Strict Mode）。这个文件你很少需要修改。

src/App.jsx 是你的第一个组件，也是你要编辑的文件。Vite 生成的版本导入了三张图片（一张主图以及 Vite 和 React 的 logo）和 App.css，并以 export default App 结尾。这和在开头写 export default function App() 效果一样，本页的示例用的就是后一种写法。

第一次修改

打开 src/App.jsx，删掉里面的内容，换成你自己的组件。保存后浏览器就会更新。下面是一个可以照着输入的小应用，先在这里试一试：

import { useState } from 'react';

function Greeting({ name }) {
    return <h2>Hello, {name}!</h2>;
}

export default function App() {
    const [name, setName] = useState('React');

    return (
        <div>
            <Greeting name={name} />
            <label>
                Your name:{' '}
                <input value={name} onChange={(e) => setName(e.target.value)} />
            </label>
        </div>
    );
}

在输入框里打字，标题会跟着变化。然后在第一个 Greeting 下面再加一个 <Greeting name="Vite" />：组件可以复用，每个副本都有自己的 name。

App.jsx 变大以后，把组件移到单独的文件中，比如 src/Greeting.jsx，导出它们，再在用到的地方导入。组件一页会介绍具体做法。

生产构建

开发服务器用于编写代码。准备发布时，构建应用：

npm run build
npm run preview

npm run build 会编译 JSX，打包并压缩你的代码，然后把静态文件写入 dist/ 文件夹。npm run preview 会在本地提供这个文件夹，方便你检查真正的构建结果。把 dist/ 上传到任意静态托管服务即可。构建时 React 还会切换到生产模式，速度更快，也不会显示开发警告。

Create React App 已被弃用

多年来，标准的起步方式是 npx create-react-app my-app。2025 年 2 月，React 团队弃用了 Create React App，它已不再维护。很多旧教程仍在使用它，所以你会在其中看到 react-scripts start 和 src/index.js 入口文件；组件本身在 Vite 项目中的用法完全一样。

替代方案：

• Vite：适合客户端应用、学习项目或小组件，也就是上面的配置方式。
• 框架：需要内置路由、服务端渲染或数据加载时使用。常见选择是 Next.js 和 React Router 的框架模式：

npx create-next-app@latest my-app
npx create-react-router@latest my-app

要把现有的 Create React App 项目迁移到 Vite，主要步骤是：安装 vite 和 @vitejs/plugin-react 并移除 react-scripts；添加一个加载 React 插件的 vite.config.js；把 index.html 从 public/ 移到项目根目录，去掉 %PUBLIC_URL% 占位符，并为入口文件添加 <script type="module" src="/src/index.jsx"> 标签；把包含 JSX 的文件重命名为 .jsx；把 REACT_APP_ 环境变量改名为 VITE_，并从 import.meta.env 读取；最后把 package.json 中的 react-scripts 命令替换为 vite、vite build 和 vite preview。

在现有页面中加入 React

React 不一定要接管整个页面。你可以把它渲染到现有网站的某一个元素中，比如服务端渲染的商城页面里的购物车小组件。编译 JSX 仍然需要 Vite 这样的打包工具。安装这两个包：

npm install react react-dom

然后在希望由 React 控制的元素上创建一个根：

import { createRoot } from 'react-dom/client';
import Cart from './Cart.jsx';

const container = document.getElementById('cart');
createRoot(container).render(<Cart />);

#cart 之外的内容保持原样。一个页面上可以创建多个根，每个元素一个，它们各自独立运行。