第二篇：工程化搭建 — Vite + React + TypeScript + TailwindCSS 全解析

第二篇：工程化搭建 --- Vite + React + TypeScript + TailwindCSS 全解析

本文目标：理解项目中的每一个配置文件是干什么的，能独立从零搭建一个同样技术栈的项目。

一、为什么选这套技术栈？

面试官大概率会问："你为什么用 React 而不是 Vue？为什么用 Vite 而不是 Webpack？"

1.1 React vs Vue

维度	React	Vue
入门难度	较高	较低（模板语法直观）
大型项目	✅ 生态成熟，社区庞大	✅ 也可胜任
AI 训练数据	React 代码占多数	相对较少
编程范式	函数式，JSX（JS + HTML）	SFC 单文件组件（template+script+style）
AI 时代优势	GitHub Copilot / Cursor 对 React 的训练数据更多	-

面试回答思路：不贬低 Vue，而是说"React 的 JSX 在 AI 辅助编程时代有天然优势 ------ AI 生成 JSX 就是生成 JavaScript，不需要额外学习模板语法。而且 React 的函数式编程思想与 AI 时代的函数封装理念高度吻合。"

1.2 Vite vs Webpack

维度	Webpack	Vite
冷启动	慢（需要打包整个项目）	极快（ESM 按需编译）
HMR 热更新	随项目变大而变慢	几乎瞬时
开发体验	配置繁琐	开箱即用
构建	成熟稳定	基于 Rollup，也很快
生态	最成熟	快速追赶，主流项目已迁移

Vite 利用了浏览器原生 ES Module 支持，开发时不需要打包，直接按需编译。这就像餐厅从"先做好所有菜再上"变成了"客人点什么做什么"。

二、项目初始化命令

先从零搭建一遍。打开终端：

bash 复制代码

# 使用 Vite 官方模板创建项目
npm create vite@latest webgpu -- --template react-ts

# 进入项目
cd webgpu

# 安装依赖
npm install

# 安装 TailwindCSS v4
npm install tailwindcss @tailwindcss/vite

# 启动开发服务器
npm run dev

三、配置文件逐行拆解

3.1 package.json --- 项目身份证

json 复制代码

{
  "name": "webgpu",          // 项目名
  "private": true,            // 私有项目，防止意外发布到 npm
  "version": "0.0.0",         // 版本号，开发阶段用 0.0.0
  "type": "module",           // 🔑 关键：启用 ES Module（import/export）
  "scripts": {
    "dev": "vite",            // 启动开发服务器
    "build": "tsc -b && vite build",  // 先类型检查，再构建
    "lint": "eslint .",       // 代码规范检查
    "preview": "vite preview" // 预览生产构建
  }
}

"type": "module" 这一行很关键。Node.js 默认使用 CommonJS（require/module.exports），设置这个后就能用现代的 import/export 语法。没有它，Vite 和很多现代工具将无法正常工作。

依赖分析

perl 复制代码

{
  "dependencies": {
    "react": "^19.2.6",       // React 核心库
    "react-dom": "^19.2.6"    // React 的 DOM 渲染器
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^6.0.1",   // Vite 的 React 插件
    "vite": "^8.0.12",                   // 构建工具
    "typescript": "~6.0.2",              // TypeScript 编译器
    "@types/react": "^19.2.14",          // React 的类型定义
    "@types/react-dom": "^19.2.3",       // ReactDOM 的类型定义
    "tailwindcss": "...",                // 通过 @tailwindcss/vite 引入
    "eslint": "^10.3.0",                 // 代码规范工具
    "typescript-eslint": "^8.59.2"       // TS 的 ESLint 插件
  }
}

关键区分 ：dependencies 是生产环境需要的包（会打包到最终产物），devDependencies 是开发阶段需要的包（不会进最终产物）。React 是运行时需要的 → dependencies。TypeScript、ESLint、Vite 只在开发构建时用 → devDependencies。

3.2 vite.config.ts --- 构建引擎的配置文件

javascript 复制代码

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

export default defineConfig({
  plugins: [
    react(),        // ① 让 Vite 理解 React JSX 语法
    tailwindcss()   // ② 在构建时扫描代码，提取用到的 Tailwind 类名
  ],
})

Vite 的插件系统非常简洁：

react() ：内部使用 Oxc（Rust 写的极速编译器）来处理 JSX 转换，比之前的 Babel 方案快 10-100 倍
tailwindcss() ：扫描你的代码中的 class 名（如 flex、text-4xl），只把用到的 CSS 规则打包进最终文件。如果你没用某个类名，它对应的 CSS 就不会出现在产物中 ------ 这就是 TailwindCSS 能保持 CSS 文件体积极小的原因。

3.3 tsconfig.json 体系

这个项目用了 TypeScript 的**项目引用（Project References）**特性，把配置拆成了三个文件：

入口：tsconfig.json

json 复制代码

{
  "files": [],    // 空数组，自己不编译任何文件
  "references": [
    { "path": "./tsconfig.app.json" },    // 引用应用代码的配置
    { "path": "./tsconfig.node.json" }    // 引用 Node 端代码的配置
  ]
}

这种拆分的好处是：

应用代码（src/）和构建配置（vite.config.ts）使用不同的编译选项
类型检查时可以并行处理两个项目
避免了"一个文件里既要 DOM 类型又要 Node 类型"的混乱

应用配置：tsconfig.app.json

json 复制代码

{
  "compilerOptions": {
    "target": "es2023",              // 编译目标：ES2023 标准
    "lib": ["ES2023", "DOM"],        // 可用类型：ES2023 API + DOM API
    "module": "esnext",              // 模块系统：最新 ES Module
    "skipLibCheck": true,            // 跳过 .d.ts 类型文件的检查（加速）
    
    "moduleResolution": "bundler",   // 🔑 模块解析方式：按打包器（Vite）的方式
    "allowImportingTsExtensions": true, // 允许 import 时写 .ts / .tsx 后缀
    "verbatimModuleSyntax": true,    // 强制保留 import/export 语法
    "moduleDetection": "force",      // 所有 .ts 文件视为 ES Module
    "noEmit": true,                  // 不生成 JS 文件（Vite 负责编译）
    "jsx": "react-jsx",             // JSX 转换方式
    
    // Linting 规则
    "noUnusedLocals": true,          // 未使用的局部变量 → 报错
    "noUnusedParameters": true,      // 未使用的参数 → 报错
    "noFallthroughCasesInSwitch": true // switch 穿透 → 报错
  },
  "include": ["src"]                 // 只检查 src 目录
}

几个重要的点：

"jsx": "react-jsx" ：这是 React 17 引入的新 JSX 转换。以前你需要 import React from 'react'，现在不需要了。编译器会自动注入。
"noEmit": true：TypeScript 只做类型检查，不生成 JS 文件。实际的编译由 Vite 完成。这是现代前端工具链的标配做法。
"moduleResolution": "bundler" ：告诉 TS 按打包器的方式解析模块路径。这意味着你可以省略文件后缀、使用 src/components/Button 这样的路径。

3.4 TailwindCSS 4 配置

TailwindCSS v4 的配置方式相比 v3 有了巨大变化。

v3 方式（旧）：

css 复制代码

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: { extend: {} },
  plugins: [],
}

v4 方式（新，本项目用的）：

scss 复制代码

/* src/index.css --- 只需要一行 */
@import "tailwindcss";

惊人的简洁！V4 把配置全部移到了 CSS 中，通过 @theme 等 CSS 指令来定制，而且自动检测内容文件路径，不需要手动配置 content。

这也是为什么我们的 index.css 只有一行代码的原因。

3.5 eslint.config.js --- 代码规范守护者

arduino 复制代码

// ESLint 的 "flat config" 格式（v9+ 的新格式）

ESLint 在项目中的作用是约束代码风格、提前发现潜在错误。比如：

定义了变量但没用 → 抱错
引用了不存在的变量 → 报错
类型不匹配 → 配合 TypeScript 报错

面试加分项：ESLint 不只是"找茬工具"。在多人协作中，统一的代码风格可以减少 Code Review 中的无效讨论。配合 Prettier 使用可以实现"保存即格式化"的完美体验。

四、目录结构设计

csharp 复制代码

webgpu/
├── public/
│   ├── favicon.svg        # 网站图标
│   └── icons.svg          # SVG 图标集合
├── src/
│   ├── assets/
│   │   ├── hero.png       # 首页展示图
│   │   ├── react.svg      # React logo
│   │   └── vite.svg       # Vite logo
│   ├── components/
│   │   └── Progress.tsx    # 进度条组件
│   ├── App.css             # App 组件样式
│   ├── App.tsx             # 主应用组件
│   ├── index.css           # 全局样式（引入 TailwindCSS）
│   └── main.tsx            # 应用入口
├── index.html              # HTML 入口
├── package.json            # 项目配置
├── tsconfig.json           # TS 配置入口
├── tsconfig.app.json       # 应用 TS 配置
├── tsconfig.node.json      # Node 端 TS 配置
├── vite.config.ts           # Vite 配置
├── eslint.config.js        # ESLint 配置
└── .npmrc                   # npm 配置

这个结构遵循了 React 社区的最佳实践：

组件独立目录 ：components/ 下每个组件一个文件
静态资源分离 ：assets/ 存放图片、SVG
配置在根目录：所有配置文件顶级放置，一目了然

五、从 HTML 到 React 应用的启动流程

让我们追踪一个完整的启动链：

markdown 复制代码

1. 用户访问网页
   ↓
2. index.html 加载
   <script type="module" src="/src/main.tsx"></script>
   ↓
3. main.tsx 执行
   import App from './App.tsx'
   createRoot(document.getElementById('root')!).render(<App />)
   ↓
4. React 创建根节点，挂在到 <div id="root">
   ↓
5. App 组件渲染
   - 检测 WebGPU 支持
   - 渲染 Load Model 按钮
   - 等待用户交互
   ↓
6. 用户点击 Load Model
   - Transformers.js 开始下载模型
   - 状态更新 → React 重渲染
   - 进度条实时更新

关键入口代码：

javascript 复制代码

// main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

createRoot ：React 18+ 的新 API（之前是 ReactDOM.render），支持并发渲染
StrictMode：开发模式下会额外执行一些检查（如检测副作用、废弃 API 警告等），生产环境无影响
! ：非空断言，告诉 TypeScript 这个元素一定存在

六、本篇小结

这篇文章我们深入了解了项目的工程化基础：

Vite 利用浏览器原生 ESM 实现极速开发体验，配置简洁
TypeScript 采用 Project References 拆分配置，应用和构建各司其职
TailwindCSS v4 极致简化，一行 @import "tailwindcss" 即可使用
ESLint 保障代码质量和团队协作规范
整个配置文件体系环环相扣，每个文件都有明确的职责

下一篇我们将真正进入 React 的世界，看看如何用函数式组件的思想来构建 AI 聊天界面。