React 基础版（一）环境搭建

目录

• 1. React 安装环境前置要求
• 2. 通过 Vite 搭建 React 项目
• 3. React 项目目录结构详解
• 4. package.json 核心字段详解
• 5. npm 语义化版本号与版本限定符
• 6. package-lock.json 详解
• 7. Vite 多路径别名配置

1. React 安装环境前置要求

1.1 操作系统兼容性要求

React 本身是一个跨平台的 JavaScript 库，其核心运行时不依赖于特定操作系统。主流开发环境均支持 React 项目开发：

注意：React 项目的构建产物为静态资源（HTML/JS/CSS），只要目标浏览器满足运行条件即可，部署环境无特殊限制。

1.2 Node.js 最低版本要求及版本选择建议

React 18 官方推荐 Node.js 版本为 14.0.0 及以上。使用 Vite 作为构建工具时，建议环境满足以下要求：

• 最低版本：Node.js >= 14.18.0（Vite 4 的硬性要求）
• 推荐版本：Node.js 18.x LTS 或 20.x LTS
• 原因：长期支持版本（LTS）提供稳定的补丁更新，且 Vite 5/6 对 Node.js 18+ 有更好支持

可通过以下命令检查当前 Node.js 版本：

node -v

1.3 包管理工具版本要求

React 项目支持 npm、yarn、pnpm 等包管理工具，推荐版本如下：

检查命令：

npm -v
yarn -v
pnpm -v

1.4 浏览器兼容性要求

React 18 支持的现代浏览器范围如下：

• Chrome / Edge：最新版及最近两个大版本
• Firefox：最新版及最近两个大版本
• Safari：14.1+
• Chrome Android / Safari iOS：最新版

对于 IE 浏览器，React 18 已正式放弃对 Internet Explorer 的支持。若项目必须兼容旧版浏览器，需额外引入 core-js 等 polyfill，并考虑降级至 React 17。

1.5 开发工具与 VS Code 推荐插件

推荐使用 Visual Studio Code 作为 React 项目的主要开发工具，以下为建议安装的插件：

2. 通过 Vite 搭建 React 项目

2.1 全局环境检查

在创建项目前，应确认本地环境已安装 Node.js 与包管理工具：

node -v      # 输出示例：v18.20.0
npm -v       # 输出示例：10.2.3

若版本过低，建议访问 Node.js 官网（https://nodejs.org）下载 LTS 版本进行安装。

2.2 创建项目的命令行操作

Vite 提供了官方的项目脚手架工具，支持通过 npm、yarn 或 pnpm 创建 React 项目。以下以 npm 为例：

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

参数说明：

• my-react-app：项目名称，创建后生成同名目录
• --template react：指定使用 React 模板

Vite 也支持交互式创建：

npm create vite@latest

执行后按提示选择：

1. Project name：输入项目名称
2. Select a framework：选择 React
3. Select a variant：选择 JavaScript 或 TypeScript

2.3 依赖安装步骤

进入项目目录并安装依赖：

cd my-react-app
npm install

安装完成后，项目根目录将生成 node_modules 文件夹，并存有项目所需的全部依赖包。

2.4 本地开发服务启动流程

执行以下命令启动本地开发服务器：

npm run dev

启动成功后，终端会显示类似如下信息：

  VITE v5.0.0  ready in 320 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

打开浏览器访问 http://localhost:5173/ 即可查看默认页面。

2.5 项目创建后的初始验证步骤

1. 访问页面，确认默认 React + Vite 页面正常渲染；
2. 修改 src/App.jsx 中的内容，观察浏览器是否热更新（HMR）；
3. 检查 src/main.jsx 是否正确调用 ReactDOM.createRoot；
4. 执行 npm run build 测试生产构建是否成功；
5. 检查 dist 目录是否生成构建产物。

3. React 项目目录结构详解

使用 Vite 创建 React 项目后，默认目录结构如下：

my-react-app/
├── node_modules/          # 项目依赖包
├── public/                # 静态资源目录
├── src/                   # 源码目录
│   ├── assets/            # 项目资源（图片、字体、样式等）
│   ├── App.css            # 根组件样式
│   ├── App.jsx            # 根组件
│   ├── index.css          # 全局样式
│   └── main.jsx           # 应用入口文件
├── .eslintrc.cjs          # ESLint 配置
├── .gitignore             # Git 忽略规则
├── index.html             # 应用入口 HTML
├── package.json           # 项目元数据与依赖
├── package-lock.json      # npm 依赖锁定文件
├── README.md              # 项目说明文档
└── vite.config.js         # Vite 构建配置

3.1 文件夹详解

node_modules/

• 作用：存放项目通过 npm install 下载的所有依赖包及其子依赖。
• 文件类型：第三方 JavaScript 库、二进制文件、类型声明文件等。
• 使用场景：运行项目、打包构建时由 Node.js 加载模块。
• 注意事项：该目录通常不应提交到代码仓库，需通过 package.json 与 package-lock.json 重新生成。

public/

• 作用：存放不需要经过构建工具处理的静态资源。
• 文件类型：图片、字体、JSON 数据、全局脚本、robots.txt 等。
• 使用场景：通过绝对路径直接引用，如 /logo.png。
• 特点：public 目录下的文件会原样复制到构建输出目录（dist）。

src/

• 作用：项目核心源代码目录，React 组件、业务逻辑、样式等均存放于此。
• 常用子目录划分规范：

3.2 核心配置文件详解

vite.config.js

• 作用：Vite 构建工具的核心配置文件，用于定义别名、代理、插件、构建输出等。
• 核心使用场景：配置路径别名、开发服务器代理、React 插件、构建优化等。

index.html

• 作用：整个单页应用（SPA）的入口 HTML 文件。
• 核心使用场景：引入根挂载点（<div id="root"></div>），加载 src/main.jsx。

.gitignore

• 作用：定义 Git 版本控制应忽略的文件与目录。
• 常见内容：node_modules/、.env、.DS_Store、dist/ 等。

.vscode/

• 作用：存放 VS Code 工作区配置，便于团队统一开发环境。
• 常见文件：settings.json（编辑器配置）、extensions.json（推荐插件）、launch.json（调试配置）。

4. package.json 核心字段详解

package.json 是 Node.js 项目的配置文件，记录了项目元数据、依赖与脚本命令。以下是 React + Vite 项目中常见字段的详细说明：

4.1 scripts 字段详解

Vite 项目默认的 scripts 配置如下：

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "preview": "vite preview",
  "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
}

• dev：启动本地开发服务器，默认端口 5173
• build：执行生产环境构建，输出到 dist 目录
• preview：预览生产构建结果
• lint：运行 ESLint 检查代码规范

5. npm 语义化版本号与版本限定符

5.1 版本号结构

语义化版本（Semantic Versioning，SemVer）格式为：MAJOR.MINOR.PATCH

示例：react@18.2.0 表示主版本 18，次版本 2，修订版本 0。

5.2 版本限定符规则

5.3 特殊版本标识

5.4 不同前缀在依赖安装时的版本拉取差异

假设 package.json 中声明 react: "^18.2.0"：

• 当 React 最新版本为 18.3.1 时，npm 会安装 18.3.1；
• 当 React 最新版本为 19.0.0 时，npm 不会安装 19.0.0，因为主版本变化会破坏兼容性；

若声明为 react: "~18.2.0"，则即使存在 18.3.0，也不会安装，仅允许 18.2.x 版本。

6. package-lock.json 详解

6.1 生成逻辑

package-lock.json 由 npm 在执行 npm install 时自动生成。它精确记录了当前 node_modules 目录中所有依赖包的版本、下载地址与依赖关系。

6.2 核心作用

1. 依赖版本锁定：确保团队成员、CI/CD 环境与生产环境安装完全一致的依赖版本；
2. 安装速度优化：npm 可直接读取锁定文件中的解析结果，减少版本计算时间；
3. 依赖树结构固化：完整记录直接依赖与间接依赖的层级关系，避免依赖解析差异；
4. 安全性与可复现性：保证项目在不同时间、不同机器上的构建结果一致。

6.3 文件内部核心字段含义

6.4 与 package.json 的版本关联规则

• package.json 描述的是“希望安装的版本范围”；
• package-lock.json 描述的是“实际安装的精确版本”；
• 当 package-lock.json 存在时，npm 优先遵循锁定文件安装依赖；
• 使用 npm install <package> 会更新 package.json 与 package-lock.json；
• 使用 npm ci 会严格依据 package-lock.json 安装，不更新范围。

6.5 提交到代码仓库的必要性

强烈建议将 package-lock.json 提交到代码仓库。原因包括：

• 保证团队开发环境依赖一致；
• CI/CD 流水线可通过 npm ci 实现可复现安装；
• 避免不同成员安装到不同版本的依赖导致构建结果不一致；
• 提升 npm install 的解析速度。

6.6 与 yarn.lock、pnpm-lock.yaml 的核心差异

7. Vite 多路径别名配置

在 React 项目中，使用路径别名可以避免大量 ../../../ 形式的相对路径，提升代码可读性与维护性。本章节将配置以下别名：

7.1 在 vite.config.js 中配置路径别名

首先，在 vite.config.js 中引入 path 模块，并在 resolve.alias 中配置别名：

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import path from "path";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@components": path.resolve(__dirname, "./src/components"),
      "~img": path.resolve(__dirname, "./src/assets/images"),
      "#types": path.resolve(__dirname, "./src/types"),
    },
  },
});

注意：在 ESM 项目中，__dirname 需要额外处理。若出现未定义错误，可使用以下方式兼容：

import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

7.2 配置 VS Code 路径提示

为了让 VS Code 在输入别名时提供自动补全与路径提示，需要在项目根目录创建 jsconfig.json（JavaScript 项目）或 tsconfig.json（TypeScript 项目）。

JavaScript 项目：jsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "~img/*": ["src/assets/images/*"],
      "#types/*": ["src/types/*"]
    }
  },
  "include": ["src"]
}

TypeScript 项目：tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "~img/*": ["src/assets/images/*"],
      "#types/*": ["src/types/*"]
    }
  },
  "include": ["src"]
}

配置完成后，建议重启 VS Code 以使路径提示生效。

7.3 别名在项目代码中的使用示例

引用组件

import Header from "@components/Header";
import Button from "@components/Button";

function App() {
  return (
    <div>
      <Header />
      <Button>点击我</Button>
    </div>
  );
}

export default App;

引用图片资源

import logo from "~img/logo.png";

function App() {
  return (
    <div>
      <img src={logo} alt="Logo" />
    </div>
  );
}

export default App;

引用类型定义（TypeScript 项目）

import type { UserInfo } from "#types/user";

const user: UserInfo = {
  id: 1,
  name: "张三",
};

引用通用工具函数

import { formatDate } from "@/utils/date";

const dateStr = formatDate(new Date());

7.4 验证别名是否生效

1. 启动开发服务器：npm run dev；
2. 打开浏览器访问页面，确认无模块解析错误；
3. 在 VS Code 中输入别名，检查是否有路径自动补全提示；
4. 执行 npm run build 测试生产构建是否成功。

总结

本文档系统梳理了 React 项目从环境准备、项目创建、目录结构、package.json 字段、版本号规则、package-lock.json 到 Vite 路径别名配置的完整知识体系。掌握上述内容后，开发者可以独立完成 React + Vite 项目的搭建与基础配置，并为后续组件开发、状态管理、路由配置等进阶学习奠定坚实基础。