前端基石：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 Eventsjszip:^3.10.1,// ZIP 文件处理mermaid:^11.14.0// 图表绘制},devDependencies:{// 构建工具vite:^8.0.1,vitejs/plugin-react:^6.0.1,// TypeScripttypescript:~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 的核心配置文件importpathfrompathimport{defineConfig}fromviteimportreactfromvitejs/plugin-reactimporttailwindcssfromtailwindcss/vite// https://vite.dev/config/exportdefaultdefineConfig({// 插件系统扩展 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,}},},})配置解析插件系统vitejs/plugin-react提供 React 快速刷新Fast Refresh功能tailwindcss/viteTailwind CSS v4 的 Vite 插件路径别名将映射到src目录这样我们可以使用/components/Button而不是../../components/Button开发服务器代理解决跨域问题前端运行在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.tsimport{create}fromzustand// 定义应用状态接口interfaceAppState{count:number// 计数器状态increment:()void// 增加计数的方法decrement:()void// 减少计数的方法}// 创建 storeexportconstuseAppStorecreateAppState((set)({// 初始状态count:0,// 更新状态的方法increment:()set((state)({count:state.count1})),decrement:()set((state)({count:state.count-1})),}))代码逐行解析导入create函数从 zustand 导入创建 store 的函数定义状态接口使用 TypeScript 接口明确定义状态结构和方法签名创建 storecreate函数接收一个回调函数返回初始状态和方法set函数zustand 提供的状态更新函数接收一个更新器函数或新状态状态更新set((state) ({ ... }))使用当前状态计算新状态在组件中使用 Store// src/components/Counter.tsximport{useAppStore}from/storeexportfunctionCounter(){// 从 store 中提取需要的状态和方法const{count,increment,decrement}useAppStore()return(div classNamep-4 border rounded-lg shadow-smh2 classNametext-lg font-semibold mb-2计数器示例/h2div classNameflex items-center gap-4button onClick{decrement}classNamepx-3 py-1 bg-gray-200 rounded hover:bg-gray-300-/buttonspan classNametext-xl font-bold{count}/spanbutton onClick{increment}classNamepx-3 py-1 bg-blue-500 text-white rounded hover:bg-blue-600/button/div/div)}实战启动你的第一个 React 应用步骤 1克隆项目并安装依赖# 克隆项目gitclone https://github.com/2692341798/InkWords.gitcdInkWords/frontend# 安装依赖使用 npm 或 yarnnpminstall# 或yarninstall步骤 2启动开发服务器npmrun dev# 或yarndev启动成功后你会看到类似下面的输出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.tsxexportfunctionWelcome(){return(div classNamemin-h-screen bg-gradient-to-br from-blue-50to-indigo-100flex items-center justify-center p-4div classNamemax-w-2xl w-full bg-white rounded-2xl shadow-xl p-8h1 classNametext-4xl font-bold text-gray-900 mb-4 欢迎来到 InkWords/h1p classNametext-gray-600 mb-6这是一个现代化的全栈博客平台使用 ReactTypeScriptTailwindCSS构建。/pdiv classNamespace-y-4div classNameflex items-center gap-2div classNamew-3 h-3 bg-green-500 rounded-full/divspan classNamefont-medium✅ 前端服务已启动/span/divdiv classNameflex items-center gap-2div classNamew-3 h-3 bg-blue-500 rounded-full/divspan classNamefont-medium 依赖安装完成/span/divdiv classNameflex items-center gap-2div classNamew-3 h-3 bg-purple-500 rounded-full/divspan classNamefont-medium⚡ Vite 构建工具运行中/span/div/div/div/div)}步骤 5更新主应用// src/App.tsximport{Welcome}from./components/Welcomeimport{Counter}from./components/CounterfunctionApp(){return(divWelcome/div classNamep-8Counter//div/div)}exportdefaultApp项目架构解析让我们通过一个架构图来理解整个前端项目的结构用户访问index.htmlVite 开发服务器React 应用入口App 组件路由系统全局状态UI 组件页面组件Zustand StoreShadcn UITailwind CSS应用状态用户状态UI 状态开发代理后端 API静态资源架构说明入口层index.html和main.tsx是应用的起点核心层React 组件树构成应用的主体状态层Zustand 管理全局状态UI 层Tailwind CSS Shadcn UI 提供样式和组件网络层Vite 代理处理前后端通信常见问题与解决方案Q1依赖安装失败怎么办# 清除缓存后重试npmcache clean--forcerm-rfnode_modules package-lock.jsonnpminstallQ2端口被占用怎么办# 修改 Vite 配置中的端口# 在 vite.config.ts 中添加server:{port:3000, // 使用3000端口 //... 其他配置}Q3TypeScript 报类型错误# 检查 TypeScript 配置npx tsc--noEmit# 只检查类型不生成文件# 如果缺少类型定义安装对应的 types 包npminstall--save-dev types/包名总结通过本章的学习我们完成了项目初始化基于 Vite React 18 TypeScript 搭建了现代化前端项目工具配置配置了 Vite、TypeScript、ESLint 等开发工具样式集成集成了 Tailwind CSS v4 和 Shadcn UI 组件库状态管理引入了 Zustand 并创建了基础 Store开发环境配置了开发服务器和 API 代理这个前端骨架为后续的功能开发奠定了坚实基础。我们有了快速的开发服务器Vite类型安全的代码TypeScript现代化的样式方案Tailwind CSS可复用的 UI 组件Shadcn UI简洁的状态管理Zustand现在我们的前端项目已经骨架齐全可以开始填充血肉——开发具体的功能模块了。下期预告在下一篇文章中我们将深入探讨JWT 鉴权体系令牌生成与解析。你将学习到JWTJSON Web Token的工作原理如何在前端安全地存储和传输令牌实现自动刷新令牌机制构建受保护的路由和权限控制处理常见的认证/授权场景准备好进入用户认证的世界了吗我们下期见扩展阅读Vite 官方文档Tailwind CSS v4 新特性Zustand 最佳实践TypeScript 入门教程实战练习尝试修改useAppStore添加一个reset方法将计数器归零创建一个新的组件使用 Shadcn UI 的按钮和卡片组件配置 ESLint添加自定义的代码规范规则