219 lines
6.9 KiB
Markdown
219 lines
6.9 KiB
Markdown
---
|
||
tags: [React, TypeScript, Frontend, Vite]
|
||
create time: 2026-04-29 22:00
|
||
---
|
||
|
||
# 环境搭建与项目结构
|
||
|
||
## 概述
|
||
|
||
本文档作为 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 速度慢等问题。以下是三种方案的横向对比：
|
||
|
||
```mermaid
|
||
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 方案，开发服务器启动时间从数十秒降至亚秒级。
|
||
|
||
```bash
|
||
# 创建项目（选择 react-ts 模板）
|
||
npm create vite@latest my-app -- --template react-ts
|
||
cd my-app
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器（自动打开浏览器）
|
||
npm run dev
|
||
```
|
||
|
||
### Vite 核心配置
|
||
|
||
`vite.config.ts` 是开发服务器的中枢，通常需要配置路径别名、代理和插件：
|
||
|
||
```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 方案
|
||
|
||
```bash
|
||
# --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 # 入口文件
|
||
```
|
||
|
||
### 模块依赖关系
|
||
|
||
理解各目录之间的引用关系对维护项目至关重要：
|
||
|
||
```mermaid
|
||
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 核心选项
|
||
|
||
```jsonc
|
||
{
|
||
"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 引入的新格式：
|
||
|
||
```js
|
||
// 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-测试]]
|