安装Vite

刘春龙原创2026/3/5...大约 6 分钟

安装 Vite 📦

环境要求 💎

在开始安装 Vite 之前，请确保你的开发环境满足以下条件：

前提条件

Node.js：建议使用 18.0 或更高版本（Vite 5 要求 Node.js 18+，Vite 6 要求 20.19+ 或 22.12+）
包管理器：npm、yarn、pnpm 任选其一（推荐使用 pnpm，速度更快且节省磁盘空间）
编辑器：推荐使用 VSCode，配合 Vue/React 官方插件可获得完善的代码提示

查看 Node.js 版本

node -v
npm -v

方式一：使用官方脚手架（推荐） 💎

Vite 官方提供了多种模板的创建命令，最推荐 的方式是使用 npm create vite@latest：

创建项目

npm create vite@latest my-vite-app

执行命令后，命令行会提示选择框架：

? Select a framework: » - Use arrow-keys. Return to submit.
>   Vanilla
    Vue
    React
    Preact
    Lit
    Svelte
    Solid
    Qwik
    Others

然后选择语言（JavaScript / TypeScript）：

? Select a variant: » - Use arrow-keys. Return to submit.
>   TypeScript
    JavaScript

如果想跳过交互式选择，可以直接通过参数指定模板：

# 创建 Vue + TS 模板
npm create vite@latest my-vite-app -- --template vue-ts

# 创建 Vue + JS 模板
npm create vite@latest my-vite-app -- --template vue

# 创建 React + TS 模板
npm create vite@latest my-vite-app -- --template react-ts

# 创建 React + JS 模板
npm create vite@latest my-vite-app -- --template react

# 创建原生 JS 项目
npm create vite@latest my-vite-app -- --template vanilla

# 创建原生 TS 项目
npm create vite@latest my-vite-app -- --template vanilla-ts

常用模板对照表

模板	说明
`vanilla`	原生 JavaScript
`vanilla-ts`	原生 TypeScript
`vue`	Vue 3 + JavaScript
`vue-ts`	Vue 3 + TypeScript
`react`	React + JavaScript
`react-ts`	React + TypeScript
`react-swc`	React + SWC + JavaScript
`react-swc-ts`	React + SWC + TypeScript
`preact`	Preact + JavaScript
`preact-ts`	Preact + TypeScript
`lit`	Lit + JavaScript
`lit-ts`	Lit + TypeScript
`svelte`	Svelte + JavaScript
`svelte-ts`	Svelte + TypeScript
`solid`	Solid + JavaScript
`solid-ts`	Solid + TypeScript

安装依赖并启动

# 进入项目目录
cd my-vite-app

# 安装依赖（推荐 pnpm）
pnpm install
# 或者：npm install / yarn install

# 启动开发服务器
pnpm dev
# 或者：npm run dev / yarn dev

启动成功后，控制台会显示如下信息：

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/
  ➜  press h + enter to show help

打开浏览器访问 http://localhost:5173/ 即可看到项目运行效果：

浏览器打开后，页面中央会显示当前框架的 Logo（Vue/React/Svelte 等）、项目名称以及 "Click on the Vite logo to learn more" 等引导文字，并且所有交互与热更新都能立即生效。

打包构建

开发完成后，使用以下命令打包生产环境代码：

pnpm build
# 或者：npm run build / yarn build

打包完成后，会在项目根目录生成 dist 文件夹，这就是可以部署到服务器上的静态资源。

预览打包结果

可以通过 pnpm preview 在本地预览打包后的产物：

pnpm preview

方式二：在已有项目中集成 Vite 💎

如果你想将已有的项目迁移到 Vite，只需三步即可。

第一步：安装 Vite

# Vue 项目
npm install -D vite @vitejs/plugin-vue

# React 项目
npm install -D vite @vitejs/plugin-react

# Vue + React 通用模板
npm install -D vite

第二步：创建 vite.config.ts

在项目根目录创建 vite.config.ts：

Vue 项目

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

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

React 项目

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

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

第三步：修改 package.json

将原本的构建命令替换为 Vite 命令：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}

第四步：创建入口 HTML

在项目根目录创建 index.html：

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Vite App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

注意

Vite 的入口 HTML 必须放在项目根目录，而不是 public 目录。

方式三：使用社区脚手架 💎

除了官方脚手架，社区也提供了很多优秀的脚手架工具。

create-vue（Vue 官方） :ghost

# 创建 Vue 3 项目（带更多可选项）
npm create vue@latest

# 启动项目
cd <your-project-name>
npm install
npm run dev

create-vue 提供了更多企业级项目特性，例如：Router、Pinia、TypeScript、Vitest、ESLint、Prettier 等。

create-electron-vite（Electron） :ghost

如果想用 Vite + Electron 开发桌面应用，可以使用：

npm create @quick-start/electron@latest my-electron-app
cd my-electron-app
npm install
npm run dev

create-vite-extra（更多模板） :ghost

npm create vite-extra@latest

配置文件详解 💎

Vite 的配置文件 vite.config.ts 支持多种配置项，下面列出最常用的配置：

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

export default defineConfig({
  // 项目根目录
  root: '.',

  // 公共基础路径
  base: './',

  // 开发服务器配置
  server: {
    host: '0.0.0.0',       // 允许局域网访问
    port: 5173,            // 端口
    open: true,            // 自动打开浏览器
    cors: true,            // 开启 CORS
    proxy: {               // 代理配置
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },

  // 路径别名
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
    },
  },

  // 构建配置
  build: {
    outDir: 'dist',                  // 输出目录
    assetsDir: 'assets',            // 静态资源目录
    sourcemap: false,               // 是否生成 sourcemap
    minify: 'esbuild',              // 压缩方式
    target: 'es2015',               // 编译目标
    chunkSizeWarningLimit: 1500,    // 包体积警告阈值
    rollupOptions: {
      output: {
        // 自定义分包策略
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          echarts: ['echarts'],
        },
      },
    },
  },

  // CSS 预处理器
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "@/styles/variables.scss";`,
      },
    },
  },

  // 插件
  plugins: [vue()],
})

常见问题 💎

安装慢怎么办？ 👻

国内网络环境下，建议使用淘宝镜像：

# 临时使用镜像
npm install --registry=https://registry.npmmirror.com

# 全局设置镜像
npm config set registry https://registry.npmmirror.com

或者直接使用 pnpm（速度更快）：

# 安装 pnpm
npm install -g pnpm

# 使用 pnpm 安装依赖
pnpm install

端口被占用 👻

Vite 默认使用 5173 端口，如果被占用会自动切换。如果想指定端口：

// vite.config.ts
export default defineConfig({
  server: {
    port: 8080, // 修改端口
    strictPort: true, // 严格模式：端口被占用时直接报错
  },
})

局域网内其他人无法访问 👻

默认情况下 Vite 仅监听 localhost，局域网内其他设备无法访问。修改配置：

export default defineConfig({
  server: {
    host: '0.0.0.0', // 监听所有网络接口
  },
})

路径别名不生效 👻

如果 @/ 路径别名不生效，需要在 tsconfig.json 中同步配置：

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

打包后页面空白 👻

通常是路径配置问题。vite.config.ts 中的 base 字段控制资源的公共前缀：

export default defineConfig({
  // 部署到根路径
  base: '/',

  // 部署到子路径
  base: '/myapp/',
})

启动报错：esbuild 相关 👻

如果是 Windows 系统，可能遇到 esbuild 平台兼容问题：

# 在 package.json 中加入
"scripts": {
  "dev": "set NODE_OPTIONS=--openssl-legacy-provider && vite"
}

或重新安装 esbuild：

npm install esbuild --force

小结

本章我们学习了 Vite 的多种安装方式：

官方脚手架：npm create vite@latest，推荐方式
现有项目集成：手动安装 vite 并配置
社区脚手架：create-vue、create-electron-vite 等

同时介绍了 vite.config.ts 常用配置项以及常见问题的解决方案。

至此，本章节的学习就到此结束了，如有疑惑，可对接技术客服进行相关咨询。