第一章：本地开发环境搭建与工程化配置

第一章：本地开发环境搭建与工程化配置

摘要: 一个高效、规范的本地开发环境是快速掌握新技术的前提。在本章中，我们将回归开发的本质，优先在 Windows 中搭建一个快如闪电的本地 React 开发环境。我们将从使用 pnpm 初始化 Vite 项目开始，深入配置路径别名、ESLint 与 Prettier，并与 Cursor / VS Code 深度集成，实现保存即格式化的“心流”体验。本章的最终目标，是为您构建一个与专业团队对齐的、高度规范化的本地开发起点，为后续学习扫清一切障碍。

在本章中，我们将循序渐进地完成以下核心任务：

  1. 首先，我们将在 Windows 环境中准备好 Node.js 和 pnpm。
  2. 接着，我们将使用 pnpm create vite 初始化一个纯净的 React + TypeScript 项目。
  3. 然后，我们将解剖项目的初始结构与启动流程，精确理解其工作原理。
  4. 之后，我们将深入 vite.config.ts 和 tsconfig.json，配置路径别名等开发效率优化。
  5. 最后，我们将引入并配置 ESLint 和 Prettier，建立一套现代化的代码质量与风格保障体系，并与编辑器深度集成。

1.1. 基础环境准备：配置 Windows 与 Node.js

对于现代前端开发而言，一个配置正确的本地环境是高效工作的基石。我们将直接在 Windows 系统上进行环境搭建。

1.1.1. 在 Windows 中安装 Node.js

首先，您需要访问 Node.js 官方网站，下载适用于 Windows 的 长期支持版 (LTS) 安装程序。

下载后，双击运行 .msi 安装文件，按照安装向导的提示，使用默认选项一路“下一步”即可完成安装。安装程序会自动将 node.exe 和 npm 添加到系统的 PATH 环境变量中。

安装完成后，您可以打开一个新的 PowerShell 或命令提示符窗口，执行以下命令来验证安装是否成功：

1
2
node -v
npm -v

如果能看到对应的版本号输出，则代表 Node.js 环境已准备就绪。

1.1.2. 安装 pnpm

pnpm 是一个快速、节省磁盘空间的包管理器。我们推荐使用它来替代 npm。在安装好 Node.js 之后，于终端中执行以下命令进行全局安装：

1
2
# 全局安装 pnpm
npm install -g pnpm

1.2. 初始化项目：从纯净的 Vite 模板开始

我们将在 Windows 的文件系统中创建项目。

打开您的终端，导航到您希望创建项目的目录（例如 D:\projects），然后运行：

1
2
# 在 projects 目录下创建我们的项目
pnpm create vite prorise-react-guide

Vite 会引导您完成几个选择：

1
2
✔ Select a framework: › React
✔ Select a variant: › TypeScript

按照提示，进入项目目录，安装依赖，并启动它：

1
2
3
cd prorise-react-guide
pnpm install
pnpm run dev

Vite 启动后，会提供一个本地 URL，如 http://localhost:5173/。您可以在 Windows 的浏览器中打开此地址。看到旋转的 React Logo，代表您的项目地基已成功铺设。

1.3. 项目初探：解剖 React 应用的启动流程

理解现有文件如何协同工作，是进行任何修改前的必要步骤。

初始项目结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# prorise-react-guide/
├── public/
│   └── vite.svg
├── src/
│   ├── assets/
│   │   └── react.svg
│   ├── App.css
│   ├── App.tsx         # 根组件
│   ├── index.css
│   ├── main.tsx        # 应用的入口文件
│   └── vite-env.d.ts
├── .eslintrc.cjs
├── .gitignore
├── index.html          # SPA 的 HTML 宿主页面
├── package.json
├── tsconfig.json
├── tsconfig.node.json
└── vite.config.ts

启动流程追溯:

  1. index.html (宿主页面): 浏览器加载的第一个文件，是整个单页应用（SPA）的“舞台”。它的 <body> 中包含一个关键的 <div> 元素：<div id="root"></div>，这是 React 应用将会被注入的目标位置。同时，它通过 <script type="module" src="/src/main.tsx"></script> 引入了应用的入口脚本。
  2. src/main.tsx (应用入口): 这是 React 应用的启动引擎。它的核心职责是：
    • 导入 React 和 ReactDOM 库。
    • 导入根组件 App。
    • 使用 ReactDOM.createRoot() 找到 index.html 中的 <div id="root"> 元素，并创建一个 React 渲染根。
    • 调用 root.render() 方法，将 <App /> 组件及其所有子组件渲染到该 DOM 节点中。
  3. src/App.tsx (根组件): 这是组件树的最顶层。在初始模板中，它是一个标准的函数组件，返回一段 JSX（JavaScript XML），这段 JSX 定义了我们在浏览器中看到的初始界面。

1.4. 提升开发效率：配置路径别名

随着项目复杂度的增加，深层相对路径 (../../../) 会严重影响代码的可读性和可维护性。我们将配置路径别名，用 @ 符号直达 src 目录。

1.4.1. 配置 Vite

首先，修改 vite.config.ts 文件，告知 Vite 如何解析这个别名。

文件路径: vite.config.ts (修改)

1
2
3
4
5
6
7
8
9
10
11
12
13
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path' // 引入 Node.js 'path' 模块
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
  // 新增 resolve 配置
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})

1.4.2. 配置 TypeScript

接着，修改 tsconfig.json 文件，让 TypeScript 的语言服务也能理解这个别名，从而提供正确的类型检查和路径补全。

文件路径: tsconfig.json (修改)

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

关键一步: 修改 tsconfig.json 后，您需要重启 TypeScript 服务才能让更改生效。在 Cursor / VS Code 中，按下 Ctrl+Shift+P (或 Cmd+Shift+P)，输入并选择 TypeScript: Restart TS Server。

1.5. 代码规范体系：ESLint 与 Prettier

我们将建立一套自动化的代码规范体系，确保代码质量和风格的一致性。

1.5.1. 安装核心依赖

Vite 的 React 模板已包含部分 ESLint 配置，但我们需要对其进行扩展和现代化。

1
2
3
# 卸载模板自带的旧版插件，并安装我们需要的现代化套件
pnpm remove eslint-plugin-react-refresh && \
pnpm add -D @eslint/js typescript-eslint eslint-plugin-react-hooks eslint-plugin-react eslint-config-prettier globals
  • @eslint/js, typescript-eslint: ESLint 核心与 TypeScript 解析支持。
  • eslint-plugin-react, eslint-plugin-react-hooks: React 官方推荐的规则集，用于检查 Hooks 的正确使用等。
  • eslint-config-prettier: 用于关闭所有与 Prettier 冲突的 ESLint 规则。

1.5.2. 现代化 ESLint 配置 (eslint.config.js)

我们将放弃传统的 .eslintrc 文件，全面转向名为 eslint.config.js 的现代化扁平配置文件。

首先，删除项目根目录下的 .eslintrc.cjs 文件，然后新建 eslint.config.js。

文件路径: eslint.config.js (新建)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
import globals from "globals";
import eslintJs from "@eslint/js";
import tseslint from "typescript-eslint";
import eslintPluginReact from "eslint-plugin-react";
import eslintPluginReactHooks from "eslint-plugin-react-hooks";
import eslintConfigPrettier from "eslint-config-prettier";

export default tseslint.config(
  // 全局忽略文件
  {
    ignores: ["dist", "node_modules", "*.config.js", "public"],
  },
  // 应用于所有文件的基础配置
  eslintJs.configs.recommended,
  ...tseslint.configs.recommended,
  // React 相关的专属配置
  {
    files: ["src/**/*.{ts,tsx}"],
    plugins: {
      react: eslintPluginReact,
      "react-hooks": eslintPluginReactHooks,
    },
    languageOptions: {
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
      },
      globals: {
        ...globals.browser,
      },
    },
    rules: {
      ...eslintPluginReact.configs.recommended.rules,
      ...eslintPluginReactHooks.configs.recommended.rules,
      "react/react-in-jsx-scope": "off", // React 17+ 无需在作用域中引入 React
    },
  },
  // 必须放在最后，用于关闭与 Prettier 冲突的规则
  eslintConfigPrettier
);

1.5.3. 配置 Prettier 与编辑器集成

  1. 安装 Prettier:
1
pnpm add -D prettier eslint-plugin-prettier
  1. 创建 Prettier 配置文件: 在项目根目录创建 .prettierrc.json。

文件路径: .prettierrc.json (新建)

1
2
3
4
5
6
7
{
  "semi": false,
  "singleQuote": true,
  "printWidth": 80,
  "tabWidth": 2,
  "trailingComma": "es5"
}

1.6. 集成现代化样式方案：Tailwind CSS

为了实现极致的开发效率和保持样式的一致性，我们的整个 React 学习之旅将以 Tailwind CSS 作为首选样式解决方案。现在，我们将其集成到通过 Vite 创建的项目中。

1.6.1. 安装核心依赖

在您的项目根目录终端中，运行以下命令来安装 tailwindcss 及其对等依赖。

1
pnpm add -D tailwindcss postcss autoprefixer
  • tailwindcss: Tailwind CSS 核心库。
  • postcss: 一个用 JavaScript 工具转换 CSS 的平台，Tailwind 依赖它来处理 CSS。
  • autoprefixer: 一个 PostCSS 插件，可以自动为 CSS 规则添加浏览器厂商前缀。

1.6.2. 生成配置文件

接下来，运行 Tailwind CSS 的初始化命令，它会自动在项目根目录创建两个关键的配置文件：tailwind.config.js 和 postcss.config.js。

1
pnpm tailwindcss init -p

1.6.3. 配置 Tailwind 的模板路径

打开新生成的 tailwind.config.js 文件，我们需要告诉 Tailwind 去哪里扫描我们的文件，以便它能找到所有使用的原子类并生成对应的 CSS。

文件路径: tailwind.config.js (修改)

1
2
3
4
5
6
7
8
9
10
11
12
/** @type {import('tailwindcss').Config} */
export default {
  // 关键：将 content 数组更新为以下内容
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

这个配置意味着 Tailwind 会去扫描根目录的 index.html 文件以及 src 目录下所有以 .js, .ts, .jsx, 或 .tsx 结尾的文件。

1.6.4. 引入 Tailwind 指令

现在，我们需要在我们的主 CSS 文件中引入 Tailwind 的三个核心指令层。

打开 src/index.css 文件，清空所有内容，然后替换为以下三行：

文件路径: src/index.css (修改)

1
2
3
@tailwind base;
@tailwind components;
@tailwind utilities;

1.6.5. 清理并验证

为了避免样式冲突，请确保 src/App.css 文件是空的，并且 src/App.tsx 中没有 import './App.css'。

现在，重新运行 pnpm run dev，并用以下代码替换 src/App.tsx 的内容来验证 Tailwind 是否生效：

文件路径: src/App.tsx (临时修改以验证)

1
2
3
4
5
6
7
8
9
10
11
function App() {
  return (
    <div className="bg-slate-800 text-white min-h-screen flex justify-center items-center">
      <h1 className="text-3xl font-bold underline">
        你好, Tailwind CSS!
      </h1>
    </div>
  )
}

export default App

如果页面背景变为深灰色，文字变为白色且带有下划线，那么 Tailwind CSS 已成功集成！至此，一个专业、高效且规范化的本地 React 开发环境已经搭建完毕。它为您后续深入学习 React 的核心概念和生态工具，提供了一个坚如磐石的起点。