前端基石：React + Vite + TypeScript 项目搭建

前端基石：React + Vite + TypeScript 项目搭建

本文是《InkWords 全栈开发实战》系列的第 5 章。我们将从零开始搭建一个现代化的 React 前端项目，使用 Vite 作为构建工具，TypeScript 提供类型安全，并集成 Tailwind CSS、Shadcn UI 和 Zustand 等主流技术栈。本文所有代码均来自 InkWords 项目仓库。

为什么选择这个技术栈？

在开始代码之前，我们先理解一下为什么选择这些技术：

• Vite：新一代前端构建工具，启动速度极快，开发体验优秀
• React 18：当前最流行的前端框架，拥有庞大的生态系统
• TypeScript：为 JavaScript 添加静态类型，提高代码质量和开发效率
• Tailwind CSS：实用优先的 CSS 框架，快速构建自定义设计
• Shadcn UI：基于 Radix UI 的可定制组件库
• Zustand：轻量级状态管理库，API 简洁直观

这就像建造一座房子：Vite 是我们的施工队（快速高效），React 是建筑框架（结构稳定），TypeScript 是施工图纸（确保准确），Tailwind 是装修材料（灵活美观），Shadcn UI 是预制构件（质量可靠），Zustand 是房屋的智能控制系统（管理状态）。

项目初始化与配置

1. 项目结构概览

让我们先看看项目的基础结构：

frontend/
├── package.json          # 项目依赖和脚本
├── vite.config.ts       # Vite 配置文件
├── tsconfig.json        # TypeScript 配置
├── index.html           # 入口 HTML 文件
└── src/
    ├── store/           # 状态管理
    │   └── index.ts     # Zustand store
    └── ...              # 其他源码目录

2. package.json 深度解析

package.json 是项目的"身份证"和"说明书"，包含了所有依赖和脚本：

{
  "name": "frontend",
  "private": true,
  "version": "0.0.0",
  "type": "module",           // 使用 ES 模块
  "scripts": {
    "dev": "vite",           // 开发服务器
    "build": "tsc -b && vite build",  // 构建生产版本
    "lint": "eslint .",      // 代码检查
    "preview": "vite preview" // 预览生产构建
  },
  "dependencies": {
    // 核心框架
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
    
    // UI 组件库
    "@base-ui/react": "^1.3.0",
    "lucide-react": "^1.7.0",     // 图标库
    "shadcn": "^4.1.2",           // UI 组件
    
    // 样式相关
    "@tailwindcss/vite": "^4.2.2",
    "tailwindcss": "^4.2.2",
    "tailwind-merge": "^3.5.0",   // 合并 Tailwind 类名
    "tw-animate-css": "^1.4.0",   // 动画库
    
    // 状态管理
    "zustand": "^5.0.12",
    
    // 工具库
    "class-variance-authority": "^0.7.1", // 动态类名
    "clsx": "^2.1.1",                     // 条件类名
    
    // 数据可视化
    "recharts": "^3.8.1",          // 图表库
    
    // Markdown 处理
    "react-markdown": "^10.1.0",
    "remark-gfm": "^4.0.1",        // GitHub Flavored Markdown
    
    // 其他功能
    "@microsoft/fetch-event-source": "^2.0.1", // Server-Sent Events
    "jszip": "^3.10.1",             // ZIP 文件处理
    "mermaid": "^11.14.0"           // 图表绘制
  },
  "devDependencies": {
    // 构建工具
    "vite": "^8.0.1",
    "@vitejs/plugin-react": "^6.0.1",
    
    // TypeScript
    "typescript": "~5.9.3",
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "@types/node": "^24.12.2",
    
    // 代码质量
    "eslint": "^9.39.4",
    "@eslint/js": "^9.39.4",
    "typescript-eslint": "^8.57.0",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.5.2"
  }
}

关键点解析：

• type: "module"：使用 ES6 模块系统，支持 import/export 语法
• scripts：定义了开发工作流，从开发到构建再到预览
• dependencies：生产环境依赖，会打包到最终产物中
• devDependencies：开发环境依赖，只在开发时使用

3. Vite 配置详解

vite.config.ts 是 Vite 的核心配置文件：

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

// https://vite.dev/config/
export default defineConfig({
  // 插件系统：扩展 Vite 功能
  plugins: [
    react(),           // React 热更新支持
    tailwindcss(),     // Tailwind CSS 集成
  ],
  
  // 路径别名配置：简化导入路径
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"), // 将 @ 映射到 src 目录
    },
  },
  
  // 开发服务器配置
  server: {
    proxy: {
      // 代理 API 请求到后端
      '/api': {
        target: 'http://localhost:8080', // 后端地址
        changeOrigin: true,              // 修改请求源
        timeout: 120000,                 // 超时时间（2分钟）
      },
      // 代理静态资源请求
      '/uploads': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      }
    },
  },
})

配置解析：

1. 插件系统：

   • @vitejs/plugin-react：提供 React 快速刷新（Fast Refresh）功能
   • @tailwindcss/vite：Tailwind CSS v4 的 Vite 插件

2. 路径别名：

   • 将 @ 映射到 src 目录，这样我们可以使用 @/components/Button 而不是 ../../components/Button

3. 开发服务器代理：

   • 解决跨域问题：前端运行在 localhost:5173，后端在 localhost:8080
   • /api 代理：所有以 /api 开头的请求转发到后端
   • /uploads 代理：静态文件请求也转发到后端

4. TypeScript 配置

tsconfig.json 是 TypeScript 的配置文件：

{
  "files": [],
  "compilerOptions": {
    "baseUrl": ".",  // 解析非相对模块的基础目录
    "paths": {
      "@/*": ["./src/*"]  // 路径映射，与 Vite 配置保持一致
    }
  },
  "references": [
    { "path": "./tsconfig.app.json" },  // 应用配置
    { "path": "./tsconfig.node.json" }   // Node.js 配置
  ]
}

这是 TypeScript 的项目引用配置，使用了"项目引用"特性来分离应用代码和工具代码的配置。

状态管理：Zustand 入门

Zustand 是一个轻量级的状态管理库，API 设计非常简洁。让我们看看如何在项目中配置基础 Store：

基础 Store 实现

// src/store/index.ts
import { create } from 'zustand'

// 定义应用状态接口
interface AppState {
  count: number           // 计数器状态
  increment: () => void   // 增加计数的方法
  decrement: () => void   // 减少计数的方法
}

// 创建 store
export const useAppStore = create<AppState>((set) => ({
  // 初始状态
  count: 0,
  
  // 更新状态的方法
  increment: () => set((state) => ({ 
    count: state.count + 1 
  })),
  
  decrement: () => set((state) => ({ 
    count: state.count - 1 
  })),
}))

代码逐行解析：

1. 导入 create 函数：从 zustand 导入创建 store 的函数
2. 定义状态接口：使用 TypeScript 接口明确定义状态结构和方法签名
3. 创建 store ：create 函数接收一个回调函数，返回初始状态和方法
4. set 函数：zustand 提供的状态更新函数，接收一个更新器函数或新状态
5. 状态更新 ：set((state) => ({ ... })) 使用当前状态计算新状态

在组件中使用 Store

// src/components/Counter.tsx
import { useAppStore } from '@/store'

export function Counter() {
  // 从 store 中提取需要的状态和方法
  const { count, increment, decrement } = useAppStore()
  
  return (
    <div className="p-4 border rounded-lg shadow-sm">
      <h2 className="text-lg font-semibold mb-2">计数器示例</h2>
      <div className="flex items-center gap-4">
        <button
          onClick={decrement}
          className="px-3 py-1 bg-gray-200 rounded hover:bg-gray-300"
        >
          -
        </button>
        <span className="text-xl font-bold">{count}</span>
        <button
          onClick={increment}
          className="px-3 py-1 bg-blue-500 text-white rounded hover:bg-blue-600"
        >
          +
        </button>
      </div>
    </div>
  )
}

实战：启动你的第一个 React 应用

步骤 1：克隆项目并安装依赖

# 克隆项目
git clone https://github.com/2692341798/InkWords.git
cd InkWords/frontend

# 安装依赖（使用 npm 或 yarn）
npm install
# 或
yarn install

步骤 2：启动开发服务器

npm run dev
# 或
yarn dev

启动成功后，你会看到类似下面的输出：

  VITE v8.0.1  ready in 320 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

步骤 3：访问应用

打开浏览器，访问 http://localhost:5173，你应该能看到应用运行起来了！

步骤 4：创建你的第一个组件

让我们创建一个简单的欢迎组件：

// src/components/Welcome.tsx
export function Welcome() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 to-indigo-100 
                    flex items-center justify-center p-4">
      <div className="max-w-2xl w-full bg-white rounded-2xl shadow-xl p-8">
        <h1 className="text-4xl font-bold text-gray-900 mb-4">
          🚀 欢迎来到 InkWords！
        </h1>
        <p className="text-gray-600 mb-6">
          这是一个现代化的全栈博客平台，使用 React + TypeScript + Tailwind CSS 构建。
        </p>
        <div className="space-y-4">
          <div className="flex items-center gap-2">
            <div className="w-3 h-3 bg-green-500 rounded-full"></div>
            <span className="font-medium">✅ 前端服务已启动</span>
          </div>
          <div className="flex items-center gap-2">
            <div className="w-3 h-3 bg-blue-500 rounded-full"></div>
            <span className="font-medium">📦 依赖安装完成</span>
          </div>
          <div className="flex items-center gap-2">
            <div className="w-3 h-3 bg-purple-500 rounded-full"></div>
            <span className="font-medium">⚡ Vite 构建工具运行中</span>
          </div>
        </div>
      </div>
    </div>
  )
}

步骤 5：更新主应用

// src/App.tsx
import { Welcome } from './components/Welcome'
import { Counter } from './components/Counter'

function App() {
  return (
    <div>
      <Welcome />
      <div className="p-8">
        <Counter />
      </div>
    </div>
  )
}

export default App

项目架构解析

让我们通过一个架构图来理解整个前端项目的结构：
用户访问
index.html
Vite 开发服务器
React 应用入口
App 组件
路由系统
全局状态
UI 组件
页面组件
Zustand Store
Shadcn UI
Tailwind CSS
应用状态
用户状态
UI 状态
开发代理
后端 API
静态资源

架构说明：

1. 入口层 ：index.html 和 main.tsx 是应用的起点
2. 核心层：React 组件树构成应用的主体
3. 状态层：Zustand 管理全局状态
4. UI 层：Tailwind CSS + Shadcn UI 提供样式和组件
5. 网络层：Vite 代理处理前后端通信

常见问题与解决方案

Q1：依赖安装失败怎么办？

# 清除缓存后重试
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Q2：端口被占用怎么办？

# 修改 Vite 配置中的端口
# 在 vite.config.ts 中添加：
server: {
  port: 3000,  // 使用 3000 端口
  // ... 其他配置
}

Q3：TypeScript 报类型错误？

# 检查 TypeScript 配置
npx tsc --noEmit  # 只检查类型，不生成文件

# 如果缺少类型定义，安装对应的 @types 包
npm install --save-dev @types/包名

总结

通过本章的学习，我们完成了：

1. 项目初始化：基于 Vite + React 18 + TypeScript 搭建了现代化前端项目
2. 工具配置：配置了 Vite、TypeScript、ESLint 等开发工具
3. 样式集成：集成了 Tailwind CSS v4 和 Shadcn UI 组件库
4. 状态管理：引入了 Zustand 并创建了基础 Store
5. 开发环境：配置了开发服务器和 API 代理

这个前端骨架为后续的功能开发奠定了坚实基础。我们有了：

• 快速的开发服务器（Vite）
• 类型安全的代码（TypeScript）
• 现代化的样式方案（Tailwind CSS）
• 可复用的 UI 组件（Shadcn UI）
• 简洁的状态管理（Zustand）

现在，我们的前端项目已经"骨架齐全"，可以开始"填充血肉"------开发具体的功能模块了。

下期预告

在下一篇文章中，我们将深入探讨 JWT 鉴权体系：令牌生成与解析。你将学习到：

• JWT（JSON Web Token）的工作原理
• 如何在前端安全地存储和传输令牌
• 实现自动刷新令牌机制
• 构建受保护的路由和权限控制
• 处理常见的认证/授权场景

准备好进入用户认证的世界了吗？我们下期见！

---

扩展阅读：

• Vite 官方文档
• Tailwind CSS v4 新特性
• Zustand 最佳实践
• TypeScript 入门教程

实战练习：

1. 尝试修改 useAppStore，添加一个 reset 方法将计数器归零
2. 创建一个新的组件，使用 Shadcn UI 的按钮和卡片组件
3. 配置 ESLint，添加自定义的代码规范规则