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

工程化 |

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

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

初始化项目

这里选择 pnpm 管理项目：

$ pnpm create vite

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

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

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

pnpm i -D vite-plugin-pages

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

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()],
});

配置路径别名

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

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

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

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

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 一下，比如这样：

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

可以增加以下配置：

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, // 设置压缩精度
        },
      },
    }),
  ],
});

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

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

增加支持 tailwindcss

安装依赖包

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

pnpm add -D tailwindcss @tailwindcss/vite

配置 Vite 插件

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

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

导入 Tailwind CSS

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

@import "tailwindcss";

开始使用

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

<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指令定义，例如：
@theme {
  --color-primary: oklch(0.84 0.18 117.33);
  --color-mint-500: oklch(0.72 0.11 178);
  --font-sans: "Inter", sans-serif;
}

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

也可以：

<div style="background-color: var(--color-mint-500)">
  <!-- ... -->
</div>
  • 零配置内容检测：自动扫描项目文件，无需在  tailwind.config.js中手动配置  content路径。

Vite 企业级应用配置

常见基础配置

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 请求跨域问题。

性能优化配置

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"], // 工具库单独打包
        },
      },
    },
  },
});

环境变量管理

  1. 创建环境文件：
.env.development  # 开发环境
.env.production   # 生产环境
  1. 变量定义规则：
# 必须以VITE_开头才能被客户端访问
VITE_API_URL=https://api.example.com
VITE_DEBUG=true

安全建议：

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

区分环境按需加载配置

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

import { defineConfig } from "vite";

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

多页面应用支持

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

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 支持

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

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 常见的企业级应用配置，掌握这些配置技巧后，可以让我们的项目获得最佳的项目实践，以及最优化的打包输出，如有错误之处，欢迎指正～