从零搭建 Vite + React + Tailwind CSS 企业级应用

本文记录从零搭建 Vite + React + Tailwind CSS 项目，省去一个个官网去查阅文档，旨在方便快速丝滑的创建项目。

项目中涉及到 pages 页面自动生成路由 、svg 自动转组件 等插件，以及 Vite 企业级应用常见配置，可按需选择添加。

初始化项目

这里选择 pnpm 管理项目：

lua 复制代码

$ pnpm create vite

执行命令后按照提示操作即可。如需支持 TS 还是非 TS，又或者 TS + SWC 等等，根据自己的需求选择。

基于文件的路由（Pages 目录自动生成路由）

很多框架或脚手架（比如 next.js、nuxt.js、umi.js等）都是约定一个目录自动生成路由，如果不想用那些框架的情况下，又希望根据 pages 目录自动生成路由，可以安装这个插件：

bash 复制代码

pnpm i -D vite-plugin-pages

安装完成后进行如下配置：

javascript 复制代码

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import Pages from 'vite-plugin-pages';

// <https://vite.dev/config/>
export default defineConfig({
  plugins: [
    react(),
    Pages(),
  ],
})

配置路径别名

在引入一些文件的时候，你肯定不希望像这样：

javascript 复制代码

// 你肯定不希望像这样
import utils from '../../../../../utils';

// 一般希望这样
import utils from '@/utils';

如果想要支持类似 @/ 的路径引用别名，增加以下配置即可：

javascript 复制代码

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

// <https://vite.dev/config/>
export default defineConfig({
  plugins: [
    react(),
  ],
  resolve: {
	  // 路径别名（简化导入）
    alias: {
      '@': path.resolve(__dirname, './src')
    },
    // 自动补全扩展名
    extensions: ['.js', '.ts', '.jsx', '.tsx']
  },
})

SVG 图标文件自动转为组件

如果希望在导入 svg 图标的时候，自动转为 React 组件，虽然默认支持，但不想每次都 as 一下，比如这样：

javascript 复制代码

import { ReactComponent as IconUser } from '@/assets/user.svg';

可以增加以下配置：

javascript 复制代码

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import svgr from 'vite-plugin-svgr';

// <https://vite.dev/config/>
export default defineConfig({
  plugins: [
    react(),
    svgr({
      include: "**/*.svg",
      svgrOptions: {
        plugins: [
	        // 一般两者一起使用
	        "@svgr/plugin-svgo", // 启用 SVGO 压缩优化
	        "@svgr/plugin-jsx" // JSX 转换
	       ],
        svgoConfig: {
          floatPrecision: 2, // 设置压缩精度
        },
      },
    }),
  ],
})

这样在使用的时候就可以直接导入了，如下：

javascript 复制代码

import IconUser from '@/assets/user.svg';

增加支持 tailwindcss

安装依赖包

首先安装 Tailwind CSS 及其相关依赖：

sql 复制代码

pnpm add -D tailwindcss @tailwindcss/vite

配置 Vite 插件

将 @tailwindcss/vite 加入 vite.config.ts，如下：

javascript 复制代码

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

导入 Tailwind CSS

在 CSS 主入口文件（如 global.css / index.css）导入 tailwindcss:

css 复制代码

@import "tailwindcss";

开始使用

配置好之后就可以在项目中使用了，如：

html 复制代码

<div className="flex items-center justify-center">
	Hello World！
</div>

关于 Tailwind CSS v4

本项目使用的 Tailwind CSS v4 版本，默认使用 Lightning CSS 引擎，可直接解析 CSS 文件，无需通过 PostCSS 处理。这意味着

无需配置 PostCSS 插件 ：如 autoprefixer或 postcss-import。

配置移至 CSS 文件 ：主题、变量等直接在 CSS 中通过 @theme指令定义，例如：

css 复制代码

@theme {
  --color-primary: oklch(0.84 0.18 117.33);
  --color-mint-500: oklch(0.72 0.11 178);
  --font-sans: "Inter", sans-serif;
}

html 复制代码

<div class="bg-mint-500">
  <!-- ... -->
</div>

也可以：

html 复制代码

<div style="background-color: var(--color-mint-500)">
  <!-- ... -->
</div>

零配置内容检测 ：自动扫描项目文件，无需在 tailwind.config.js中手动配置 content路径。

Vite 企业级应用配置

常见基础配置

javascript 复制代码

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import tailwindcss from '@tailwindcss/vite'
import Pages from 'vite-plugin-pages';
import svgr from 'vite-plugin-svgr';
import path from 'path';

// <https://vite.dev/config/>
export default defineConfig({
  // base: '/app/', // 部署基础路径（子目录部署时需要）
  plugins: [
    react(),
    Pages(),
    tailwindcss(),
    svgr({
      include: "**/*.svg",
      svgrOptions: {
        plugins: ["@svgr/plugin-svgo", "@svgr/plugin-jsx"], // 启用 SVGO 压缩和 JSX 转换（两者需一起使用）
        svgoConfig: {
          floatPrecision: 2, // 设置压缩精度
        },
      },
    }),
  ],
  resolve: {
    // 配置路径别名(简化导入)
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
    // 自动补全扩展名
    extensions: ['.js', '.ts', '.jsx', '.tsx'],
  },
  // 开发服务器配置
  server: {
    port: 3000, // 端口号
    open: true, // 自动打开浏览器
    proxy: {
      '/api': {
        target: '<http://localhost:8080>', // 后端地址
        changeOrigin: true, // 修改请求源
        rewrite: (path) => path.replace(/^\/api/, ''), // 路径重写
        // secure: false  // 如果出现代理配置无效可将其打开，尝试关闭HTTPS验证
      },
    },
  },
  build: {
    outDir: 'dist', // 打包输出目录
    sourcemap: true, // 生成 sourcemap 便于调试
  },
})

字段说明：

base - 部署基础路径，当项目部署在非根路径时使用（如GitHub Pages）；
resolve.alias - 让import语句更简洁；
server.proxy：解决开发环境 API 请求跨域问题。

性能优化配置

javascript 复制代码

import { defineConfig } from 'vite'

// <https://vite.dev/config/>
export default defineConfig({
  // 生产环境专属配置
  build: {
    assetsDir: 'static', // 静态资源存放目录
    minify: 'terser', // 使用terser进行代码压缩
    chunkSizeWarningLimit: 1500, // 分块大小警告阈值(KB)
    rollupOptions: {
      output: { // 代码分割策略
        manualChunks: {
          react: ['react', 'react-dom'], // 单独打包 React 相关库
          utils: ['lodash', 'axios'] // 工具库单独打包
        }
      }
    }
  }
})

环境变量管理

创建环境文件：

bash 复制代码

.env.development  # 开发环境
.env.production   # 生产环境

变量定义规则：

ini 复制代码

# 必须以VITE_开头才能被客户端访问
VITE_API_URL=https://api.example.com
VITE_DEBUG=true

安全建议：

敏感变量应放在 .env.local（已默认在 .gitignore）

区分环境按需加载配置

针对开发或生产环境各自单独加载配置：

javascript 复制代码

import { defineConfig } from 'vite'

// <https://vite.dev/config/>
export default defineConfig(({ command, mode }) => {
  if (command === 'serve') {
    return {
      /* 开发配置 */
      server: {},
    }
  } else {
    return {
      // 生产环境专属配置
      build: {}
    }
  }
})

多页面应用支持

需要支持多页面入口的时候可以参考以下配置：

javascript 复制代码

import { defineConfig } from 'vite';
import path from 'path';

// <https://vite.dev/config/>
export default defineConfig({
  build: {
    rollupOptions: {
      // 多页面入口配置
      input: {
        main: path.resolve(__dirname, 'index.html'),
        about: path.resolve(__dirname, 'about.html')
      }
    }
  }
})

SSR支持

需要支持服务端渲染时可以添加以下配置：

javascript 复制代码

import { defineConfig } from 'vite';

// <https://vite.dev/config/>
export default defineConfig({
  ssr: {
    target: 'node', // SSR 运行环境
    noExternal: ['react-icons'] // 需要包含的打包依赖
  }
})

第三方库推荐

项目搭建好了之后，就可以去继续完善项目中常用的第三方库了，这里推荐一些比较不错的第三方库，根据自己的需求按需"食用"。

无头 UI 库

既然用上了 tailwindcss，自然少不了一些比较方便自定义 UI 的无头组件库，比如： @headlessui/react、shadcn/ui。

@headlessui/react： 由 tailwindcss 团队开发的无 UI 组件库，提供纯交互功能，完全无样式。
shadcn/ui：设计精美的组件，开放源码，可以按需复制并粘贴到您的应用程序中，无障碍，可定制。它的核心理念是提供可修改的组件代码，而不是一个传统的、黑盒式的组件库。

状态管理库

TanStack Query 和 ahooks

目前比较火热的服务数据状态管理库比如 react-query（现在叫：TanStack Query）、ahooks 等到都是非常优秀的。
zustand

一个轻量且直观的状态管理方案，基于 Hooks、**无需Context Provider、**简单易上手。

国际化

提到国际化，自然就会想到耳熟能详的 i18next。针对各个框架生态下有react-i18next、next-i18next 、vue-i18n 等等。

如果项目中需要用到国际化，建议搭配 i18next-browser-languagedetector 一起"食用"更佳，这个库可以自动检测用户的浏览器语言设置，并将其提供给i18next 来设置页面语言。

具体的搭建步骤就不再详细阐述了，可以自己搜索相关配置文章。

结语

好了，以上就是整个项目的搭建过程以及 Vite 常见的企业级应用配置，掌握这些配置技巧后，可以让我们的项目获得最佳的项目实践，以及最优化的打包输出，如有错误之处，欢迎指正～