React 19 + Vite + TypeScript 项目初始化与配置实战

安装 Tailwind CSS v3

pnpm add -D tailwindcss@3 postcss autoprefixer

本教程 刻意选择 Tailwind CSS v3，原因如下：

• shadcn/ui 官方稳定支持 v3
• eslint / prettier / tailwind 插件生态成熟
• 社区资料最完整，适合长期维护型项目
• 避免 Tailwind v4 当前的实验性不稳定因素

初始化 Tailwind CSS

npx tailwindcss init -p

会生成 tailwind.config.js 和 postcss.config.js 两个文件。

tailwind.config.js

/** @type {import('tailwindcss').Config} */ export default { content: [], theme: { extend: {}, }, plugins: [], }

postcss.config.js

export default { plugins: { tailwindcss: {}, autoprefixer: {}, }, }

将 tailwind.config.js 修改为：

/** @type {import('tailwindcss').Config} */ export default { content: [ "./index.html", "./src/**/*.{js,ts,jsx,tsx}", ], darkMode: "class", theme: { extend: {}, }, plugins: [], }

将 Tailwind 指令添加到 CSS 中

清空 ./src/index.css 中的内容，将 Tailwind 的每个 layer 的 @tailwind 指令添加到 ./src/index.css 文件中：

@tailwind base; @tailwind components; @tailwind utilities;

启动项目

pnpm run dev

修改 App.jsx，添加

<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/*" ] }, /* Bundler mode */ "moduleResolution": "bundler", "allowImportingTsExtensions": true, "verbatimModuleSyntax": true, "moduleDetection": "force", "noEmit": true, "jsx": "react-jsx", /* Linting */ "strict": true, "noUnusedLocals": true, "noUnusedParameters": true, "erasableSyntaxOnly": true, "noFallthroughCasesInSwitch": true, "noUncheckedSideEffectImports": true }, "include": ["src"] }

更新 vite.config.ts

安装 @types/node

@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 相关代码时，获得完整的类型提示、智能补全、类型检查支持。

执行以下命令：

pnpm add -D @types/node

执行结果。

在 vite.config.ts 文件中加入以下代码，使你的应用能够正确解析路径，避免报错：

修改前：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
// https://vite.dev/config/
export default defineConfig({ plugins: [react()], })

修改后：

import path from "path"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
// https://vite.dev/config/
export default defineConfig({ plugins: [react()], resolve: { alias: { "@": path.resolve(__dirname, "./src") }, }, })

shadcn/ui 工具

运行 CLI

执行 shadcn init 命令来初始化你的项目配置：

在初始化时，CLI 会询问你一些问题，用于生成 components.json。

我们稍后会使用它生成高质量 UI 组件：

pnpm dlx shadcn@latest init

具体的 color 的效果，请参考 https://ui.shadcn.com/colors，我们这里默认选择 Netural，回车。

执行成功，我们看到添加了一个 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": {} }

一个 \src\lib\utils.ts 文件：

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

更新了 \src\index.css

@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️⃣ 安装依赖

pnpm add lucide-react 

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 组件中使用（推荐）

例如在 Button 中使用图标：

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️⃣ 图标大小与颜色规范（最佳实践）

颜色统一通过 Tailwind 控制：

<Icon className="text-muted-foreground" />
<Icon className="text-primary" />

5️⃣ 为什么选择 lucide-react

本项目选择 lucide-react 作为唯一图标库，原因是：shadcn/ui 默认使用 lucideAPI 简单，学习成本极低图标风格统一，适合中后台 / 管理系统不依赖 SVG loader 或额外构建配置

6️⃣ 与 shadcn 初始化配置的关系

在你前面 components.json 中已经有：

"iconLibrary": "lucide"

这表示：

• shadcn 生成的组件 默认假设你使用 lucide-react
• 安装 lucide-react 是必须步骤
• 不需要额外配置 Vite / SVG 插件

2.3.2 安装国际化 i18n

pnpm add react-i18next i18next i18next-browser-languagedetector

2.3.3 安装主题切换

pnpm add next-themes

2.3.4 安装数据请求层（ky）

pnpm add ky

2.3.5 安装状态管理（Zustand）

pnpm add 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）

pnpm add sonner

2.3.10 安装 mock（mockjs）

pnpm add mockjs

2.3.11 安装 Recharts 图表组件

pnpm add 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

"typescript": "~5.9.3"

用途：整个项目的类型安全与工程能力基座

✔ 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

"mockjs": "^1.1.0"

✔ 通知组件（Toast）

"sonner": "^2.0.7",

✔ 图表

"recharts": "^3.5.1",

整体结构非常清晰：

• 依赖结构有明确边界
• 业务逻辑与 UI 逻辑分离
• 每个模块都有清晰职责

2.5 配置 Vite（基础版本）

vite.config.ts：

import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
// https://vite.dev/config/
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'; // 如果你使用 SVG 组件
import { defineConfig } from "vite"
// https://vite.dev/config/
export default defineConfig({ plugins: [react(), svgr()], resolve: { alias: { "@": path.resolve(__dirname, "./src") }, }, server: { port: 5173, }, })

2.6 清理默认模板

默认 App.tsx 内容过于简单，我们先清空：

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

修改 src/App.tsx：

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 环境 ✔ 清理默认模板