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

前言

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

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 创建项目

打开终端，执行：

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

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

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

1.2 升级到 React 19

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

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

然后检查 package.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，并优化开发服务器配置：

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 测试启动

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 专用）。

pnpm add tailwindcss@next @tailwindcss/vite

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

2.2 配置 Vite 插件

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

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 中的所有内容，替换为：

@import 'tailwindcss';

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

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

@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 中添加一个测试类：

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 二分法。

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 保持干净：

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 只做路由容器（后续会加路由）：

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

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

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 中加入：

"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 初始化

git init

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

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

5.2 初次提交

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

5.3 关联 GitHub 远程仓库

1. 登录 GitHub，点击右上角 “+” → “New repository”。

   • Repository name: react19-starter
   • 不要勾选 “Add a README” 或 “.gitignore”（本地已有）
   • 创建仓库。

2. 复制仓库地址（HTTPS 或 SSH），本例用 SSH：

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

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

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

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

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（记得把链接替换成你自己的仓库哦）

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