跳到主要内容基于 React 19+Vite+TypeScript 的现代前端项目初始化实战 | 极客日志TypeScript大前端
基于 React 19+Vite+TypeScript 的现代前端项目初始化实战
React 19 结合 Vite 与 TypeScript 构建现代化前端开发环境。通过 pnpm 创建项目,配置 Tailwind CSS v3 及 Shadcn UI 组件库,集成状态管理、路由、国际化等核心依赖。详解 tsconfig 路径别名设置与 Vite 插件配置,清理默认模板并验证运行环境,为后续多语言、主题切换及权限模块开发奠定基础。
萤火微光15 浏览 第 2 章:快速开始 — 使用 Vite + TypeScript 初始化项目
在上一章中,我们明确了项目目标、技术栈与未来的总体架构路线。本章将正式开始动手,从零初始化一个 基于 React 19 + TypeScript + Vite 的开发环境。
本章你将完成:
- 创建项目目录
- 初始化 Vite 项目(React + TS 模板)
- 安装所有必要依赖
- 配置基础开发环境(ESLint / Prettier / Tailwind 前置)
- 解析 package.json 结构,理解项目运行机制
完成本章后,你将拥有一个可以运行、可开发的项目基础结构,为后续多语言、主题、路由、权限等模块打下坚实基础。
2.1 创建项目目录
https://vite.dev/guide/#scaffolding-your-first-vite-project
在任意目录执行:
pnpm create vite@latest
修改 Project name,改为 web-app,回车:

选择框架,这里我们选择 React

选择 variant,这里我们选择 TypeScript


或者直接使用以下命令,指定使用 react-ts:
pnpm create vite@latest web-app --template react-ts

rolldown-vite 是将 Rolldown(一款兼容 Rollup 的 Rust 编写打包工具)集成到 Vite 的实验性方案,目标是用性能更优的 Rust 实现替代 Vite 默认的 Rollup 打包器。
Install with pnpm and start now?
cd web-app pnpm install pnpm dev
这是最基础的 React + TypeScript + Vite 项目。
2.2 运行项目,确认环境无误
2.3 安装项目所需的全部依赖
我们项目使用了丰富但结构清晰的技术栈。下面按照模块安装必要依赖。
2.3.1 安装 UI & 样式相关依赖
安装 Tailwind CSS v3
pnpm add -D tailwindcss@3 postcss autoprefixer
本教程 刻意选择 Tailwind CSS v3,原因如下:
- shadcn/ui 官方稳定支持 v3
- eslint / prettier / tailwind 插件生态成熟
- 社区资料最完整,适合长期维护型项目
- 避免 Tailwind v4 当前的实验性不稳定因素
初始化 Tailwind CSS
会生成 tailwind.config.js 和 postcss.config.js 两个文件。
export default { content: [], theme: { extend: {}, }, plugins: [], }
export default { plugins: { tailwindcss: {}, autoprefixer: {}, }, }
将 tailwind.config.js 修改为:
export default { content: [ "./index.html", "./src/**/*.{js,ts,jsx,tsx}", ], darkMode: "class", theme: { extend: {}, }, plugins: [], }
| 字段 | 作用 |
|---|
| content | Tailwind 扫描范围 |
| darkMode | 使用 class 切换,兼容 next-themes |
| extend | 注册 Token(颜色、圆角、字体等) |
将 Tailwind 指令添加到 CSS 中
清空 ./src/index.css 中的内容,将 Tailwind 的每个 layer 的 @tailwind 指令添加到 ./src/index.css 文件中:
@tailwind base;
@tailwind components;
@tailwind utilities;
<h1 className="text-3xl font-bold underline"> Hello world! </h1>
配置 TypeScript 路径别名
编辑 tsconfig.json 文件
当前版本的 Vite 将 TypeScript 配置拆分成三个文件,其中有两个需要修改。你需要在 tsconfig.json 和 tsconfig.app.json 的 compilerOptions 中添加 baseUrl 和 paths 属性:
{
"files": [],
"references": [
{ "path": "./tsconfig.app.json" },
{ "path": "./tsconfig.node.json" }
]
}
{
"files": [],
"references": [
{ "path": "./tsconfig.app.json" },
{ "path": "./tsconfig.node.json" }
],
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
编辑 tsconfig.app.json 文件
在 tsconfig.app.json 文件中加入以下代码,以便 IDE 能正确解析路径:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": [
"./src/*"
]
}
}
}
{
"compilerOptions": {
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
"target": "ES2022",
"useDefineForClassFields": true,
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"module": "ESNext",
"types": ["vite/client"],
"skipLibCheck": true,
"baseUrl": ".",
"paths": {
"@/*": [
"./src/*"
]
},
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"verbatimModuleSyntax": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"erasableSyntaxOnly": true,
"noFallthroughCasesInSwitch": true,
"noUncheckedSideEffectImports": true
},
"include": ["src"]
}
更新 vite.config.ts
@types/node 是 Node.js 的 TypeScript 类型定义文件,只要你使用 Node.js API,就必须安装。
process.env
__dirname, __filename
path, fs, crypto 等 Node 内置模块
- ESM 中使用
import.meta
- Vite 配置文件(vite.config.ts)
- Tailwind 配置文件(tailwind.config.ts)
- tsconfig 路径解析
- node 相关脚本
如果没有安装,你会看到 TypeScript 报错:
Cannot find name 'process'
Cannot find module 'path'
Cannot find name '__dirname'
让你的 TypeScript 项目在写 Node 相关代码时,获得完整的类型提示、智能补全、类型检查支持。
在 vite.config.ts 文件中加入以下代码,使你的应用能够正确解析路径,避免报错:
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
})
import path from "path"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
})
shadcn/ui 工具
执行 shadcn init 命令来初始化你的项目配置:
在初始化时,CLI 会询问你一些问题,用于生成 components.json。
pnpm dlx shadcn@latest init
执行成功,我们看到添加了一个 components.json 文件:
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "new-york",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "tailwind.config.js",
"css": "src/index.css",
"baseColor": "neutral",
"cssVariables": true,
"prefix": ""
},
"iconLibrary": "lucide",
"aliases": {
"components": "@/components",
"utils": "@/lib/utils",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
},
"registries": {}
}
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 0 0% 3.9%;
--card: 0 0% 100%;
--card-foreground: 0 0% 3.9%;
--popover: 0 0% 100%;
--popover-foreground: 0 0% 3.9%;
--primary: 0 0% 9%;
--primary-foreground: 0 0% 98%;
--secondary: 0 0% 96.1%;
--secondary-foreground: 0 0% 9%;
--muted: 0 0% 96.1%;
--muted-foreground: 0 0% 45.1%;
--accent: 0 0% 96.1%;
--accent-foreground: 0 0% 9%;
--destructive: 0 84.2% 60.2%;
--destructive-foreground: 0 0% 98%;
--border: 0 0% 89.8%;
--input: 0 0% 89.8%;
--ring: 0 0% 3.9%;
--chart-1: 12 76% 61%;
--chart-2: 173 58% 39%;
--chart-3: 197 37% 24%;
--chart-4: 43 74% 66%;
--chart-5: 27 87% 67%;
--radius: 0.5rem;
}
.dark {
--background: 0 0% 3.9%;
--foreground: 0 0% 98%;
--card: 0 0% 3.9%;
--card-foreground: 0 0% 98%;
--popover: 0 0% 3.9%;
--popover-foreground: 0 0% 98%;
--primary: 0 0% 98%;
--primary-foreground: 0 0% 9%;
--secondary: 0 0% 14.9%;
--secondary-foreground: 0 0% 98%;
--muted: 0 0% 14.9%;
--muted-foreground: 0 0% 63.9%;
--accent: 0 0% 14.9%;
--accent-foreground: 0 0% 98%;
--destructive: 0 62.8% 30.6%;
--destructive-foreground: 0 0% 98%;
--border: 0 0% 14.9%;
--input: 0 0% 14.9%;
--ring: 0 0% 83.1%;
--chart-1: 220 70% 50%;
--chart-2: 160 60% 45%;
--chart-3: 30 80% 55%;
--chart-4: 280 65% 60%;
--chart-5: 340 75% 55%;
}
}
@layer base {
* {
@apply border-border;
}
body {
@apply bg-background text-foreground;
}
}
pnpm dlx shadcn@latest add button
上面的命令会把 Button(按钮)组件 添加到你的项目中。
import { Button } from "@/components/ui/button"
function App() {
return (
<div className="flex min-h-svh flex-col items-center justify-center">
<Button>Click me</Button>
</div>
)
}
export default App
安装 lucide-react(图标库)
lucide-react 是 shadcn/ui 官方推荐的 SVG 图标库,具有以下特点:
- Tree-shaking 友好,按需引入
- TypeScript 原生支持
- 与 Tailwind / shadcn/ui 完美配合
- 无额外运行时依赖
1️⃣ 安装依赖
2️⃣ 基本使用示例
import { Search, User, Settings } from "lucide-react"
function IconDemo() {
return (
<div className="flex items-center gap-4">
<Search className="h-5 w-5 text-muted-foreground" />
<User className="h-5 w-5 text-blue-500" />
<Settings className="h-5 w-5 text-green-500" />
</div>
)
}
- 每一个图标都是一个 React 组件
className 直接控制大小与颜色
h-* w-* 来自 Tailwind
3️⃣ 在 shadcn/ui 组件中使用(推荐)
import { Plus } from "lucide-react"
import { Button } from "@/components/ui/button"
function CreateButton() {
return (
<Button>
<Plus className="mr-2 h-4 w-4" /> 新建
</Button>
)
}
这是 shadcn 官方示例风格,非常推荐在你的教程中强调。
4️⃣ 图标大小与颜色规范(最佳实践)
| 用途 | 推荐尺寸 |
|---|
| 按钮内图标 | h-4 w-4 |
| 普通功能图标 | h-5 w-5 |
| 列表 / 菜单 | h-4 w-4 |
| 图标按钮 | h-5 w-5 或 h-6 w-6 |
<Icon className="text-muted-foreground" />
<Icon className="text-primary" />
5️⃣ 为什么选择 lucide-react
本项目选择 lucide-react 作为唯一图标库,原因是:shadcn/ui 默认使用 lucideAPI 简单,学习成本极低图标风格统一,适合中后台 / 管理系统不依赖 SVG loader 或额外构建配置
6️⃣ 与 shadcn 初始化配置的关系
在你前面 components.json 中已经有:
- shadcn 生成的组件 默认假设你使用 lucide-react
- 安装 lucide-react 是必须步骤
- 不需要额外配置 Vite / SVG 插件
2.3.2 安装国际化 i18n
pnpm add react-i18next i18next i18next-browser-languagedetector
2.3.3 安装主题切换
2.3.4 安装数据请求层(ky)
2.3.5 安装状态管理(Zustand)
2.3.6 安装后端数据管理(TanStack Query)
pnpm add @tanstack/react-query
2.3.7 安装路由(React Router v7)
pnpm add react-router-dom
2.3.8 安装表单(react-hook-form + zod)
pnpm add react-hook-form zod pnpm add @hookform/resolvers
2.3.9 安装 Toast(sonner)
2.3.10 安装 mock(mockjs)
2.3.11 安装 Recharts 图表组件
2.3.13 SVG 处理插件(可选)
如果你想像 shadcn 那样使用 svg 组件:
pnpm add -D vite-plugin-svgr
我们会在 vite.config.ts 中配置它。
接下来,我们需要理解 package.json 的结构。
2.4 理解 package.json(本项目的依赖结构解析)
✔ React & Vite
"react": "^19.2.0",
"react-dom": "^19.2.0",
"vite": "^7.2.4",
"@vitejs/plugin-react": "^5.1.1",
✔ TypeScript
✔ UI & 样式系统
"tailwindcss": "^3.4.19",
"tailwind-merge": "^3.4.0",
"tailwindcss-animate": "^1.0.7",
"postcss": "^8.5.6",
"autoprefixer": "^10.4.23",
"lucide-react": "^0.561.0",
shadcn + CVA + Tailwind = 通用组件体系的三角组合。
✔ 状态与数据请求
"zustand": "^5.0.9",
"ky": "^1.14.1",
"@tanstack/react-query": "^5.90.12",
✔ 国际化
"i18next": "^25.7.2",
"i18next-browser-languagedetector": "^8.2.0",
"react-i18next": "^16.4.1",
✔ 路由
"react-router-dom": "^7.10.1",
支持最新的 Data APIs、Suspense、Lazy routes
✔ 表单 + 校验
"react-hook-form": "^7.68.0",
"zod": "^4.1.13",
"@hookform/resolvers": "^5.2.2",
✔ Mock
✔ 通知组件(Toast)
✔ 图表
- 依赖结构有明确边界
- 业务逻辑与 UI 逻辑分离
- 每个模块都有清晰职责
2.5 配置 Vite(基础版本)
import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
})
import path from "path"
import react from "@vitejs/plugin-react"
import svgr from 'vite-plugin-svgr';
import { defineConfig } from "vite"
export default defineConfig({
plugins: [react(), svgr()],
resolve: {
alias: {
"@": path.resolve(__dirname, "./src"),
},
},
server: {
port: 5173,
},
})
2.6 清理默认模板
import { useState } from 'react'
import reactLogo from './assets/react.svg'
import viteLogo from '/vite.svg'
import './App.css'
function App() {
const [count, setCount] = useState(0)
return (
<>
<div>
<a href="https://vite.dev" target="_blank">
<img src={viteLogo} className="logo" alt="Vite logo" />
</a>
<a href="https://react.dev" target="_blank">
<img src={reactLogo} className="logo react" alt="React logo" />
</a>
</div>
<h1>Vite + React</h1>
<div className="card">
<button onClick={() => setCount((count) => count + 1)}>
count is {count}
</button>
<p> Edit <code>src/App.tsx</code> and save to test HMR </p>
</div>
<p className="read-the-docs"> Click on the Vite and React logos to learn more </p>
</>
)
}
export default App
import { Button } from "@/components/ui/button"
import { Search, User, Settings, Plus } from "lucide-react"
function App() {
return (
<div className="flex min-h-screen flex-col items-center justify-center p-4 space-x-3 gap-4">
<div>App Initialized</div>
<Button>默认按钮</Button>
<Button size="sm">小</Button>
<Button size="lg">大</Button>
<Button variant="outline">描边按钮</Button>
<IconDemo />
<CreateButton />
</div>
)
}
function IconDemo() {
return (
<div className="flex items-center gap-4">
<Search className="h-5 w-5 text-muted-foreground" />
<User className="h-5 w-5 text-blue-500" />
<Settings className="h-5 w-5 text-green-500" />
</div>
)
}
function CreateButton() {
return (
<Button>
<Plus className="mr-2 h-4 w-4" /> 新建
</Button>
)
}
export default App
2.7 本章小结
✔ 初始化 Vite + React + TypeScript 项目
✔ 安装所有框架核心依赖
✔ 解析 package.json
✔ 配置基础 Vite 环境
✔ 清理默认模板
相关免费在线工具
- Base64 字符串编码/解码
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
- Base64 文件转换器
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
- Markdown转HTML
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
- HTML转Markdown
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
- JSON 压缩
通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
- JSON美化和格式化
将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online