从零搭建项目：React 19 + Vite 8 + Tailwind CSS v4 实战配置

系列第二篇：用最时髦的工具链，三十分钟搭好企业级前端项目基底

前言

上一篇文章我们定下了"从零到开源"的总体规划。现在，是时候把手弄脏，真正开始敲命令了。

React 19 刚刚稳定，Vite 跃升至 8.x，Tailwind CSS v4 也带来了革命性的配置方式------这可能是目前最"新"的一套技术栈组合。但新意味着坑多文档少，网上大部分教程还停留在 Tailwind v3 或者 Vite 5。

本文将带你一步步配置一套可用于生产环境的 React 19 + Vite 8 + Tailwind v4 项目。你不仅能学会基础搭建，还会掌握目录结构最佳实践、ESLint 9 扁平化配置，以及 Git 初始化与 GitHub 关联。

前置要求：Node.js 18+（建议 20.x），pnpm 或 npm（本文使用 pnpm，速度更快）。

一、使用 Vite 8 创建 React 19 项目

Vite 官方脚手架已经支持 React 19（需手动指定版本）。我们分三步走。

1.1 创建项目

打开终端，执行：

bash 复制代码

pnpm create vite@latest react19-starter --template react
cd react19-starter

注意：create vite@latest 默认使用最新版 Vite，目前已是 8.x。如果你用的是 npm：

bash 复制代码

npm create vite@latest react19-starter -- --template react

1.2 升级到 React 19

Vite 的 React 模板默认安装的是 React 18.3。我们需要手动升级到 19，并且更新对应的类型声明和 React DOM。

bash 复制代码

pnpm add react@19 react-dom@19
pnpm add -D @types/react@19 @types/react-dom@19

然后检查 package.json 中的依赖版本应该类似：

json 复制代码

"dependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0"
},
"devDependencies": {
  "@types/react": "^19.0.0",
  "@types/react-dom": "^19.0.0",
  "@vitejs/plugin-react": "^4.3.0",
  "vite": "^8.0.0"
}

1.3 修改 Vite 配置（可选但推荐）

打开 vite.config.js，增加路径别名 @ 指向 src，并优化开发服务器配置：

javascript 复制代码

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 3000,
    open: true, // 自动打开浏览器
  },
})

这里使用了 path 模块，需要安装 @types/node 作为开发依赖：pnpm add -D @types/node。

1.4 测试启动

bash 复制代码

pnpm run dev

浏览器打开 http://localhost:3000，看到 Vite + React 的默认页面即成功。

二、安装和配置 Tailwind CSS v4

Tailwind CSS v4 最大的变化是不再需要 tailwind.config.js ，而是通过 CSS 中的 @import 和 @theme 进行配置，原生支持 light/dark 模式切换，编译速度也大幅提升。

2.1 安装依赖

官方包名已从 tailwindcss 升级，并需要配合 @tailwindcss/vite 插件（Vite 专用）。

bash 复制代码

pnpm add tailwindcss@next @tailwindcss/vite

@next 标签目前对应 v4.0.0-beta。生产环境稳定后直接用 tailwindcss@^4 即可。

2.2 配置 Vite 插件

修改 vite.config.js，加入 @tailwindcss/vite 插件：

javascript 复制代码

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

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 3000,
    open: true,
  },
})

2.3 引入 Tailwind 样式

删除 src/index.css 中的所有内容，替换为：

css 复制代码

@import 'tailwindcss';

就这么简单！v4 会自动加载默认的 utilities、components 和 base 样式。

如果你需要自定义主题（颜色、字体、断点等），在 @import 'tailwindcss' 之后添加 @theme 块：

css 复制代码

@import 'tailwindcss';

@theme {
  --color-primary: #0ea5e9;
  --color-secondary: #64748b;
  --font-sans: 'Inter', sans-serif;
  --breakpoint-3xl: 1920px;
}

注意 v4 使用 CSS 变量语法 --key: value 来定义主题，不再需要 JS 对象。

2.4 测试 Tailwind

在 src/App.jsx 中添加一个测试类：

jsx 复制代码

function App() {
  return (
    <div className="flex items-center justify-center min-h-screen bg-gradient-to-r from-primary to-secondary">
      <h1 className="text-4xl font-bold text-white shadow-lg p-4 rounded-xl">
        Tailwind CSS v4 + React 19 🚀
      </h1>
    </div>
  )
}

export default App

重新运行 pnpm run dev，如果看到渐变色背景的大标题，说明配置成功。

三、项目目录结构设计

良好的目录结构能让团队协作和后期维护事半功倍。这里推荐一套基于功能模块 的划分方式（Feature-based），而非简单的 pages/components 二分法。

bash 复制代码

src/
├── assets/          # 静态资源（图片、字体、svg等）
├── components/      # 通用小组件（Button, Input, Modal等）
│   ├── ui/          # 无业务逻辑的纯UI组件
│   └── shared/      # 跨模块复用的业务组件
├── features/        # 业务功能模块（每个模块独立）
│   ├── auth/        # 认证模块
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/   # API调用
│   │   └── index.jsx   # 模块入口
│   └── dashboard/   # 仪表盘模块
├── hooks/           # 全局共享的hooks
├── lib/             # 第三方库封装、axios实例、工具函数
├── pages/           # 路由页面组件（或者放在features中由路由懒加载）
├── routes/          # 路由配置
├── store/           # 状态管理（Zustand/Redux等）
├── styles/          # 全局样式（Tailwind之外的自定义样式）
├── utils/           # 纯函数工具
├── App.jsx
├── main.jsx
└── index.css        # Tailwind入口文件

关键文件示例：

main.jsx 保持干净：

jsx 复制代码

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import './index.css'

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

App.jsx 只做路由容器（后续会加路由）：

jsx 复制代码

function App() {
  return <div className="app">Hello World</div>
}

export default App

有了路径别名 @，你可以这样引入：import Button from '@/components/ui/Button'。

四、ESLint 配置（扁平化时代）

ESLint 9 开始默认使用扁平配置（Flat Config），.eslintrc.js 已成为历史。我们需要创建 eslint.config.js 并集成 React 19 和 Tailwind 的规则。

4.1 安装依赖

bash 复制代码

pnpm add -D eslint @eslint/js eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-tailwindcss globals

@eslint/js：ESLint 9 的内置推荐配置。
eslint-plugin-tailwindcss：自动排序和校验 Tailwind 类名。

4.2 编写 `eslint.config.js`

javascript 复制代码

import js from '@eslint/js'
import reactPlugin from 'eslint-plugin-react'
import reactHooksPlugin from 'eslint-plugin-react-hooks'
import tailwindPlugin from 'eslint-plugin-tailwindcss'
import globals from 'globals'

export default [
  js.configs.recommended,
  ...tailwindPlugin.configs['flat/recommended'],
  {
    files: ['**/*.{js,jsx}'],
    plugins: {
      react: reactPlugin,
      'react-hooks': reactHooksPlugin,
    },
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: {
        ...globals.browser,
        ...globals.node,
      },
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
    settings: {
      react: {
        version: 'detect',
      },
    },
    rules: {
      'react/react-in-jsx-scope': 'off', // React 19 不需要导入React
      'react/prop-types': 'warn',
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'warn',
      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
      'tailwindcss/classnames-order': 'warn',
      'tailwindcss/no-custom-classname': 'off', // 允许自定义类名
    },
  },
  {
    ignores: ['dist', 'node_modules', '.git', '*.config.js'],
  },
]

4.3 添加 npm 脚本

在 package.json 中加入：

json 复制代码

"scripts": {
  "lint": "eslint src --ext .js,.jsx",
  "lint:fix": "eslint src --ext .js,.jsx --fix"
}

执行 pnpm run lint 检查代码规范，pnpm run lint:fix 自动修复。

如果你使用 VS Code，记得安装 ESLint 插件并启用 flat config 支持（无需额外配置）。

五、Git 初始化和 GitHub 仓库创建

5.1 本地 Git 初始化

bash 复制代码

git init

创建 .gitignore 文件（Vite 官方模板已带，确保包含以下内容）：

bash 复制代码

node_modules
dist
dist-ssr
*.local
.env
.DS_Store

5.2 初次提交

bash 复制代码

git add .
git commit -m "chore: initial commit with React 19, Vite 8, Tailwind v4"

5.3 关联 GitHub 远程仓库

登录 GitHub，点击右上角 "+" → "New repository"。
- Repository name: react19-starter
- 不要勾选 "Add a README" 或 ".gitignore"（本地已有）
- 创建仓库。
复制仓库地址（HTTPS 或 SSH），本例用 SSH：

bash 复制代码

git remote add origin git@github.com:你的用户名/react19-starter.git
git branch -M main
git push -u origin main

刷新 GitHub 页面，你的代码就全部同步上去了。

5.4 添加 GitHub Actions（可选但推荐）

在项目根目录创建 .github/workflows/ci.yml，用于每次 push 自动运行 ESLint：

yaml 复制代码

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm run lint

提交后即可在 GitHub Actions 看到检查结果。

总结与下篇预告

至此，我们已经完成了一个现代化 React 项目的完整环境搭建：

✅ 使用 Vite 8 创建 React 19 项目，并配置路径别名。
✅ 集成 Tailwind CSS v4（零配置文件，CSS-first 方式）。
✅ 设计了可扩展的目录结构。
✅ 配置了 ESLint 9 扁平化规则 + Tailwind 插件。
✅ Git 初始化并推送到 GitHub，附带 CI 流程。

你的项目基底已经具备代码规范、样式工具、自动化检查等企业级要素。接下来可以愉快地编写业务代码了。

下一篇预告：《第 3 篇：路由与状态管理 ------ React Router v7 + Zustand 最佳实践》。我们将引入新版本路由和轻量状态管理，实现多页面和全局数据流。敬请期待！

本文所有代码已上传至 GitHub：react19-starter（记得把链接替换成你自己的仓库哦）

如果你在配置中遇到任何问题，欢迎在评论区留言，我会第一时间解答。下期见～

从零搭建项目：React 19 + Vite 8 + Tailwind CSS v4 实战配置

前言

一、使用 Vite 8 创建 React 19 项目

1.1 创建项目

1.2 升级到 React 19

1.3 修改 Vite 配置（可选但推荐）

1.4 测试启动

二、安装和配置 Tailwind CSS v4

2.1 安装依赖

2.2 配置 Vite 插件

2.3 引入 Tailwind 样式

2.4 测试 Tailwind

三、项目目录结构设计

四、ESLint 配置（扁平化时代）

4.1 安装依赖

4.2 编写 eslint.config.js

4.3 添加 npm 脚本

五、Git 初始化和 GitHub 仓库创建

5.1 本地 Git 初始化

5.2 初次提交

5.3 关联 GitHub 远程仓库

5.4 添加 GitHub Actions（可选但推荐）

总结与下篇预告

4.2 编写 `eslint.config.js`