wonder/cs-note

Fork 0

Files

T

wonder 30d312ac35 Init

2026-05-24 11:42:38 +08:00

6.9 KiB

Raw Blame History

tags, create time

环境搭建与项目结构

概述

本文档作为 React 开发系列的起点，介绍从零搭建 React + TypeScript 开发环境的全过程。内容包括：主流脚手架工具的选型对比、Vite 项目初始化与核心配置、推荐的目录结构与文件命名规范。完成本章后，你将拥有一个开箱即用的工程化项目骨架，为后续学习组件开发、状态管理和路由打下基础。

[!tip] 前置知识

已安装 Node.js 18+（推荐 LTS 版本）

熟悉基本的终端操作和 npm 命令

了解 JavaScript/TypeScript 基本语法

选型决策：Vite vs CRA vs Next.js

[!question] 思考：为什么不再推荐使用 Create React App？

Create React App 已经停止维护，其 Webpack 构建在大型项目中存在明显的冷启动慢、HMR 速度慢等问题。以下是三种方案的横向对比：

graph TD
    A[项目类型] --> B["纯 SPA"]
    A --> C["SSR / 全栈应用"]
    B --> D[Vite + React]
    C --> E[Next.js App Router]
    D --> F["适合场景：前端主导、后端提供 API"]
    E --> G["适合场景：SEO 优先、服务端渲染需求"]
    
    style D fill:#61DAFB,color:#000
    style E fill:#000

Vite 方案（本文档主推）

Vite 基于原生 ES Modules + esbuild，实现毫秒级热更新。相比传统的 Webpack 方案，开发服务器启动时间从数十秒降至亚秒级。

# 创建项目（选择 react-ts 模板）
npm create vite@latest my-app -- --template react-ts
cd my-app

# 安装依赖
npm install

# 启动开发服务器（自动打开浏览器）
npm run dev

Vite 核心配置

vite.config.ts 是开发服务器的中枢，通常需要配置路径别名、代理和插件：

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import path from 'path'

export default defineConfig({
  plugins: [react()], // SWC 编译器比 Babel 更快
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'), // @ 别名指向 src 目录
    },
  },
  server: {
    proxy: {
      '/api': 'http://localhost:8080', // 开发时代理后端请求
    },
  },
})

[!note] 关键配置说明

SWC vs Babel：@vitejs/plugin-react-swc 使用 Rust 编写的 SWC 编译器，编译速度显著优于传统 Babel 方案

路径别名：配合 tsconfig.json 中的 paths 配置，可以消除项目中深层的相对导入（../../../utils → @/utils）

代理：本地开发时将 /api 开头的请求转发到后端服务，避免跨域问题

Next.js 方案

# --app: 使用 App Router（推荐）
# --typescript: 启用 TypeScript
# --tailwind: 集成 Tailwind CSS
# --src-dir: 代码放在 src 目录
npx create-next-app@latest my-app --typescript --app --tailwind --src-dir

[!warning] 选型建议

如果你的项目以 SEO、首屏加载速度、全栈能力 为核心需求，选 Next.js

如果团队更擅长 纯前端开发，后端由独立 API 服务提供，Vite + React 是更轻量合理的选择

目录结构

标准组织方式

推荐的 React + TypeScript 项目目录结构如下：

src/
├── assets/           # 静态资源（图片、字体等）
├── components/       # 通用 UI 组件（无状态或低状态）
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx
│   │   └── index.ts
│   └── Modal/
├── hooks/            # 自定义 Hooks
├── pages/            # 页面级组件
├── routes/           # 路由配置
├── stores/           # 状态管理（Zustand / Redux）
├── types/            # TypeScript 类型定义
├── utils/            # 工具函数
├── App.tsx           # 根组件
└── main.tsx          # 入口文件

模块依赖关系

理解各目录之间的引用关系对维护项目至关重要：

graph LR
    MAIN[main.tsx] --> APP[App.tsx]
    APP --> PAGES[pages - 页面组件]
    APP --> ROUTES[routes - 路由配置]
    PAGES --> COMPONENTS[components - UI组件]
    PAGES --> HOOKS[hooks - 自定义Hooks]
    PAGES --> STORES[stores - 状态管理]
    COMPONENTS --> HOOKS
    COMPONENTS --> UTILS[utils - 工具函数]
    COMPONENTS --> TYPES[types - 类型定义]
    STORES --> TYPES
    ROUTES --> PAGES

[!note] 依赖方向原则

单向依赖：上层模块（pages/stores）依赖下层模块（components/hooks/utils），反向依赖会导致循环引用

types 是基础设施：被所有层共享，但绝不反过来依赖其他业务模块

[!tip] 目录组织原则

按功能而非按类型：大型项目推荐使用 Feature-Sliced Design 或 Atomics 模式，将组件、Hook、样式、测试放在同一目录下

Barrel Export（统一导出）：每个子目录通过 index.ts 导出统一接口，简化上游 import 路径

关键配置文件

tsconfig.json 核心选项

{
  "compilerOptions": {
    "target": "ES2020",               // 目标 JS 版本
    "module": "ESNext",               // 模块系统
    "jsx": "react-jsx",               // React 17+ 自动导入 JSX transform
    "strict": true,                   // 开启严格模式
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]                // 路径别名
    }
  }
}

ESLint + Prettier 组合

推荐使用 ESLint flat config（eslint.config.js），这是 ESLint 9 引入的新格式：

// eslint.config.js (flat config)
import js from '@eslint/js'
import tseslint from 'typescript-eslint'
import reactHooks from 'eslint-plugin-react-hooks'
import globals from 'globals'

export default tseslint.config(
  js.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: { ...globals.browser },
    },
    plugins: {
      'react-hooks': reactHooks,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  }
)

[!tip] ESLint 迁移提示

旧版 .eslintrc.* 格式的配置文件可以通过 eslint --init 自动迁移为 flat config

@typescript-eslint 同时接管了 TypeScript 特有规则和 JavaScript 规则，无需再单独安装 eslint-plugin-typescript

React 19 的 ESLint 插件正在逐步推出新特性，建议保持版本同步更新

开发习惯建议

工具	用途	推荐版本
Vite	构建 & HMR	^6.x
TypeScript	类型安全	^5.x
ESLint	代码质量	^9.x (flat config)
Prettier	格式化	^3.x
Vitest	单元测试	^3.x

关联笔记

hhs/REACT/README
hhs/REACT/1. 基础篇/02-JSX 语法
hhs/REACT/3. 生态工具篇/08-路由管理
hhs/REACT/5. 工程实践篇/16-测试

6.9 KiB Raw Blame History Unescape Escape