3.1 Vite 搭建工程跑通首屏

3.1 Vite 搭建工程跑通首屏

本节摘要：用 Vite 二三十秒即可把 React 工程拉起来。本节目的是让"开发环境"这块最初的门槛变成一件不神秘的事：从脚手架到首屏跑通，再到读懂工程里的几个关键文件各管什么，为后续编码建立可靠的落脚点。

本节阅读目标
阅读完本节，你应当能够：

1. 用一条命令初始化 React 工程，并分别启动开发/构建命令。
2. 说出入口文件与根组件之间的关系。
3. 在浏览器里看到改代码实时刷新，形成第一个可复用的开发回路。

一、为什么要用脚手架

手工配置 Node、打包器、转译器非常劝退，早期 CRA 一度是默认选择，如今 Vite 因启动快、配置简单更受推荐。脚手架的价值是：环境搭建被收敛成一条命令，你可以把注意力留给代码，而不是构建配置。

二、搭建步骤

确认装好 Node 后，在终端执行：

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

第一条命令创建工程并选用 React 模板，第二条进入目录，第三条装依赖，第四条启动开发服务器。此时终端会打印本地地址，浏览器打开后你会看到 Vite 的欢迎页，改一下代码保存，页面即时刷新——HMR（热更新）在背后工作，这也正是第 3.4 节讲"改数据界面跟着变"的体感来源。

三、工程里几个关键文件都管什么

脚手架会生成一批文件，刚上手别被数量吓到，你真正要认熟的只有几个：

入口脚本的核心思想：选一个 DOM 容器，用库的方法把根组件放进去。这段通常不长：

import React from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';

const root = createRoot(document.getElementById('root'));
root.render(<App />);
​

看懂这段你就抓住了 React 应用的地基：一个 DOM 挂载点加一个根组件，剩下的都是组件树的枝叶。

四、图：从命令到首屏的落地链路

图：Vite 工程初始化与首屏渲染链路

四·一、Vite 快在哪里，值得知道的一点背景

你可能会好奇：同样一条命令，为什么 Vite 比老一代脚手架快出几倍？关键在于它把"打包"推迟到了需要的时候。开发模式下 Vite 几乎不直接把整个工程编译成一个大文件，而是按浏览器实际请求到的模块，只有用到哪个模块才去处理哪个模块，配合原生 ES 模块直接用，所以冷启动快到秒级。这一点于你现在的意义在于：它对"开发回路"的体感影响很大——保存、刷新、看到改动，中间几乎没有等待，你会更愿意频繁地试错。

顺便说明 HMR（热更新）：它比整页刷新更进一步，只把变化的那一块组件替换掉，页面状态尽量保留。你改一个子组件的样式，列表不想跳回顶部，正是 HMR 在帮你。等你学到第 3.4 节 state 时，会更加体会"保存即生效"这种开发节奏的可贵。

五、常见坑速览

• 忘记进工程目录就敲 npm run，容器会报找不到脚本，进入目录即可。
• 端口被占用时提示异常，换个端口或关掉旧进程。
• 只改了自己的文件，页面却没刷新，多半是保存路径不对或被缓存，检查是不是改对了入口文件。
• 换 npm 源后依赖装到一半失败，清理 node_modules 与锁文件再重装，往往是省时间的办法。

跑起来之后的第一份"体检清单"

首屏跑通只是起点，我建议你趁热把工程里几个"一眼看懂"的线索都确认一遍，这样后续学 React 才有落脚点。一是"改动谁、在哪触发刷新"：找一个组件函数，改它的返回 JSX，页面应立即更新，以此确认 HMR 链路是通的。二是"入口文件是谁"：在入口脚本里把根组件换成一个最简单的函数组件，看它能正常渲染，说明你对"挂载点 + 根组件"这个基地有手感了。三是"报错长什么样"：故意在组件里写一个错名变量，看终端和页面的报错提示，提前熟悉你能指望的调试信息长什么样。

这三件事看着琐碎，却会在后面无数次写错时替你省下找问题的功夫。很多初学者折腾半天不是不会写语法，而是没摸清"我改哪、应该在哪看到变化、报错该去哪看"这套最基本的回路。把回路先养熟，比多背几条 API 更能支撑你顺畅地往下学。

两个值得一开始就跟上的稳定惯例

除了上面的体检清单，脚手架时代还有两条惯例，建议你从第一天就顺着走，免得后面长歪。其一是目录内组件的就近摆放：把某个页面用到的组件、子组件、样式和间的小工具放在它自己的目录里，而不是全塞进一个 src/hooks 或 src/components 的杂物间。这样迁移、删除、复盘一个功能时都是"一整个目录带走"，内聚性立刻显现在 Git 提交能看懂、代码评审好定位上。其二是入口只做"牵线"、不做"业务"：尽量保持入口脚本干净，只负责挂载根组件，配置、拦截、全局副作用都放到更贴近业务的模块里。入口越长，越难判断"首屏到底加载了什么东西"。

这两条不是 Vite 强制的，而是社区反复踩坑后沉淀的默认偏好。它们现在看起来只是文件夹摆放和代码洁癖，等你到第 5 章组件越来越多时，会发现"是不是当初就近放、入口是不是够瘦"直接决定了你改一个全局行为要翻几张网。习惯在最初就顺好，比后面集中补救省力得多。

本节要点回顾

• 脚手架：一条 npm create vite 拉平环境门槛，命令链要记熟。
• 入口脚本：挂载点 + 根组件构成应用地基。
• HMR 回路：改代码见刷新，这就是"数据驱动视图"的日常体感。
• 别被文件数吓到：真正要认熟的核心文件就那几个。

工程跑起来了，下一节钻进最常用也最容易写错的语法——JSX，在 JavaScript 里怎么写结构、怎么插值、怎么防注入。