React / 系统课时
创建 React 项目
创建 React 项目
本课将使用 Vite 初始化一个 React 与 TypeScript 项目,并完成依赖安装和首次运行。最终你会得到一个可编辑、可热更新的本地项目,为后续 JSX、组件和状态学习提供统一环境。
学习目标
- 检查 Node.js 与 npm 是否满足项目要求
- 使用 React TypeScript 模板创建项目
- 启动开发服务器并完成首次验证
前置检查
Vite 当前要求使用受支持的 Node.js 版本。建议安装长期支持版本,并确保版本不低于 Node.js 20.19 或 22.12。先在终端检查环境:
node -v
npm -v预期输出如下,具体补丁版本可能不同:
v22.12.0
<VER>若终端提示找不到 node 或 npm,先从 Node.js 官方渠道完成安装,再关闭并重新打开终端。若版本过低,应升级 Node.js,而不是在旧环境中强行安装最新 Vite。
初始化 React TypeScript 项目
在准备存放代码的目录中执行以下命令。项目名使用 react-starter,模板使用 react-ts:
npm create vite@latest react-starter -- --template react-ts
cd react-starter
npm install预期结果:当前目录下生成 react-starter 文件夹,依赖安装完成后出现 node_modules 目录和锁文件。安装日志中的包数量、耗时和审计信息会随时间变化,不应作为是否成功的唯一判断。
命令中的第一个 -- 用于把后续参数传给 create-vite,--template react-ts 明确选择 React 与 TypeScript 模板。@latest 表示使用当前最新版脚手架,因此生成的依赖版本可能与截图或旧教程不同。
启动开发服务器
进入项目目录后运行:
npm run dev预期输出包含本地访问地址,端口可能因占用而变化:
VITE ready in <TIME> ms
Local: http://localhost:<PORT>/在浏览器打开终端显示的地址,应看到 Vite 提供的 React 初始页面。保持命令运行,修改 src/App.tsx 并保存,页面会自动刷新或局部更新。
完成最小修改
用下面内容替换 src/App.tsx,确认编辑、编译和浏览器更新链路都正常:
export default function App() {
// 用最小界面验证 TSX 编译、挂载和热更新链路。
return (
<main>
<h1>React 环境已就绪</h1>
<p>接下来开始学习 JSX 与组件。</p>
</main>
);
}预期结果:浏览器显示“React 环境已就绪”和一段说明文字,终端没有 TypeScript 或编译错误。
典型失败处理
出现 npm error 且提示网络超时,先确认浏览器可以访问 npm 软件源,并检查公司代理或终端代理配置。不要反复删除项目目录,网络问题解决后重新执行 npm install 即可。
出现 Node.js 版本不受支持的提示,应升级 Node.js。出现端口已占用时,Vite 通常会尝试下一个端口,应以终端最终输出为准。
若页面空白,先查看终端编译信息,再打开浏览器开发者工具的 Console。语法错误通常会同时显示文件名和行号,优先修复第一条错误,后续错误可能只是连锁反应。