React项目用Vite搭建要配哪些东西？CRA还能用吗？

图 0：Vite 搭建 React 项目核心配置与 CRA 存废分析总览

一、CRA 还能用吗？现状客观剖析与选型结论

Create React App（简称 CRA）曾经是 React 官方推荐了数年之久的“零配置”脚手架。但从 React 官方文档彻底重构发布起，CRA 就已被官方移除出首选推荐列表，并在官方文档中被明确划入 Legacy（过时存量）技术范畴。CRA 官方仓库的长期停滞，使得它在社区现代工具链的快速演进中被逐渐淘汰。

要客观评估“CRA 还能不能用”，需要区分“已有存量老项目”与“新建工程”两种截然不同的场景：

• 对于已上线的存量老项目：只要固定好当前的 Node.js 版本（如 Node 16 或 Node 18）以及 package-lock.json 依赖锁文件，现有项目依然可以继续构建和维护。Webpack 的成熟度使得它在不频繁改动构建流程的情况下不会突然崩溃。如果当前项目业务改动很少，盲目推倒重构迁移可能带来不必要的生产风险，继续保留维持现状是完全合理的技术决策。
• 对于面临痛点或需要升级的存量项目：如果老项目组件规模庞大，日常保存代码后热更新（HMR）经常需要等待数秒，或者因为 react-scripts 依赖锁定过死而无法平滑升级到 React 18 并发特性或 React 19，则应规划迁移到 Vite。
• 对于所有新建项目：坚决不要再使用 CRA。CRA 内部封装的 react-scripts 包含了庞大沉重的 Webpack 依赖链，随着代码文件增加，开发服务冷启动动辄耗时数十秒甚至数分钟，且配置高度黑盒化，定制 Babel 插件或 PostCSS 时往往需要 craco 等第三方工具打补丁，维护成本极高。

图 1：CRA 与 Vite 底层编译机制对比及项目选型决策路径

二、使用 Vite 搭建 React 项目的操作步骤

Vite 能够实现毫秒级冷启动与极速热更新，其底层逻辑在于：在本地开发阶段，它直接借助现代浏览器对 ES Modules（原生 ESM）的原生支持，不再把所有代码预先全量打包成一个巨大的文件；当浏览器请求某一个模块时，Vite 开发服务器通过由 Rust 编写的极速编译器（如 esbuild 或 SWC）按需转译该文件并返回。只有在执行生产构建时，Vite 才会调用成熟的 Rollup 将代码进行 Tree-shaking 并打成优化的静态包。

使用 Vite 从零初始化一个标准的 TypeScript + React 项目，按如下操作执行：

# 1. 执行官方脚手架初始化命令（以 TypeScript 模板为例）
npm create vite@latest my-react-app -- --template react-ts

# 2. 进入项目目录并安装基础依赖
cd my-react-app
npm install

# 3. 启动本地开发服务器
npm run dev

启动后，控制台会输出本地访问地址（默认是 http://localhost:5173/）。此时打开浏览器，即可看到由 Vite 生成的默认计数器演示页面。

图 2：从零初始化 Vite + React 工程的标准实操步骤

三、Vite 搭建 React 项目要配哪些东西？（六大核心配置）

刚刚通过官方模板生成的 Vite 项目，只包含了最简单的编译能力，离企业级开发规范和团队工程化标准还有明显差距。为了保证开发体验、代码提示、跨域联调以及构建稳定，以下六项配置是绝大多数 React 项目必不可少的。

1. React 编译插件选型（Babel 还是 SWC？）

在 vite.config.ts 中，React 项目必须通过插件来支持 JSX/TSX 语法的解析以及 React Fast Refresh（组件状态保持的热替换）。目前官方提供了两个主要插件：

• @vitejs/plugin-react：基于 Babel 实现。优点是生态兼容性极好，如果项目需要使用 Babel 自定义宏、Emotion 样式插件或特定代码插桩工具，选它最稳妥。
• @vitejs/plugin-react-swc：基于 Rust 编写的 SWC。在文件保存和热重载时的转译速度比 Babel 显著更快。对于绝大多数常规 React 项目，优先推荐使用 SWC 插件。

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [react()],
});

2. 路径别名（Path Alias）与 TypeScript 映射

在大型项目中，如果不配置路径别名，深层组件引用时会出现难以维护的相对路径深渊（如 import Button from '../../../../components/Button'）。配置别名需要 Vite 与 TypeScript 两端协同配置：

首先在项目内安装 Node.js 类型定义文件，以便在配置文件中使用 path 模块：

npm i -D @types/node

在 vite.config.ts 中通过 resolve.alias 指定 @ 指向 src：

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

仅仅配置 Vite 只能保证打包工具能识别路径，但编辑器和 TypeScript 仍然会报错提示找不到模块。必须同步修改 tsconfig.app.json（或 tsconfig.json）的 compilerOptions：

// tsconfig.app.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

3. 环境变量管理与强类型支持

Vite 处理环境变量的机制与 CRA 有很大不同：

• 前缀隔离安全机制：CRA 使用 REACT_APP_ 前缀，而 Vite 规定只有以 VITE_ 开头的变量才会被注入到客户端代码中。任何未加 VITE_ 前缀的变量（如数据库密码、私钥）都不会被暴露给浏览器，避免敏感信息泄露。
• 客户端读取方式：在代码中不能使用 process.env（浏览器中未定义，会导致运行时报错），必须使用 import.meta.env。

可以在项目根目录创建不同环境的配置文件：

# .env.development
VITE_APP_TITLE=我的React管理系统(开发环境)
VITE_API_BASE_URL=http://localhost:3000/api

# .env.production
VITE_APP_TITLE=我的React管理系统
VITE_API_BASE_URL=https://api.example.com/api

为了让 import.meta.env.VITE_API_BASE_URL 在编写代码时拥有完整的智能补全和类型校验，在 src/vite-env.d.ts 中扩展接口：

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string;
  readonly VITE_API_BASE_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

4. 本地开发服务器代理（Server Proxy）

前后端分离开发时，前端请求后端接口往往会遇到浏览器同源策略（CORS 跨域）拦截。在 vite.config.ts 的 server.proxy 中配置本地转发，即可彻底解决开发阶段的跨域问题：

// vite.config.ts
export default defineConfig({
  // ...其它配置
  server: {
    port: 5173,      // 指定开发服务器端口
    host: true,      // 监听所有地址，方便手机或局域网设备真机联调
    open: true,      // 服务启动时自动在默认浏览器中打开
    proxy: {
      '/api': {
        target: 'http://localhost:8080',  // 后端实际接口地址
        changeOrigin: true,               // 修改请求头中的 Host 为目标地址
        rewrite: (path) => path.replace(/^\/api/, ''), // 去除前缀（根据后端要求决定是否开启）
      },
    },
  },
});

图 3：Vite React 核心配置文件与运行架构拓扑关系

5. 样式方案接入（Tailwind CSS 与 CSS Modules）

Vite 对 CSS 提供了极佳的开箱即用支持，包括原生的 CSS Modules（只要文件名命名为 *.module.css 即可直接导入）。如果团队习惯使用现代原子化 CSS 框架 Tailwind CSS，集成步骤非常直接：

# 安装 Tailwind CSS 及其前置依赖
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

在生成的 tailwind.config.js 中配置内容匹配路径：

// tailwind.config.js
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

在 src/index.css 顶部注入指令即可全局生效：

@tailwind base;
@tailwind components;
@tailwind utilities;

6. 代码质量与格式化规范（ESLint + Prettier）

Vite 官方的 react-ts 模板已经默认内置了基础的 ESLint 配置，但在实际多人开发中，通常需要确保包含以下核心能力：

• eslint-plugin-react-hooks：严格检查 React 规则，防止在循环、条件语句中滥用 Hook 或遗漏依赖项。
• eslint-plugin-react-refresh：校验组件导出规范，确保 Vite 的 Fast Refresh 热替换能够可靠触发，而不退化为整页刷新。
• prettier：配合 eslint-config-prettier，统一步长缩进、单双引号与分号，避免因个人 IDE 设置不同产生大面积 Git 代码冲突。

四、常见避坑事项（从 CRA 迁移或新用 Vite 必看）

对于习惯了 CRA 的开发者，初次接触 Vite 很容易因为习惯差异踩入以下几个典型陷阱：

五、工程化落地对比与总结清单

为了让读者能够快速对照并检查自己的工程是否完备，下表将 CRA 与 Vite 的关键特性及常用替代方案进行了系统化梳理：

图 4：Vite + React 生产级工程化落地四维自查清单

综上所述，Create React App 完成了它在 Webpack 时代的重大历史使命，但在现代前端开发标准下已不再适合作为新项目的选型方案。使用 Vite 搭建 React 现代单页应用，只要在初始化后有序补齐插件选型、路径别名、环境隔离、代理联调、样式接入与代码规范这六项基本功，就能在享受飞速开发体验的同时，构建起稳定高效、易于长期维护的生产级项目架构。