Vue 3 + Vite 开发指南

Vite 是下一代前端构建工具，利用浏览器原生 ESM 实现极速开发启动，是 Vue 3 项目的首选构建工具。

---

创建 Vue 3 项目

# 使用 create-vite 脚手架
yarn create vite my-vue-app --template vue

# 使用 TypeScript 模板
yarn create vite my-vue-app --template vue-ts

# 进入项目并安装依赖
cd my-vue-app
yarn install

---

常用命令

开发

# 启动开发服务器
yarn dev
npx vite

# 指定端口
npx vite --port 3000

# 指定主机（局域网可访问，手机调试）
npx vite --host

# 同时指定端口和主机
npx vite --host 0.0.0.0 --port 3000

# 自动打开浏览器
npx vite --open

构建

# 生产环境构建
yarn build
npx vite build

# 指定构建模式
npx vite build --mode staging

# 分析构建产物（需要先安装 rollup-plugin-visualizer）
yarn add -D rollup-plugin-visualizer

预览

# 预览构建产物
yarn preview
npx vite preview

# 指定端口
npx vite preview --port 4173

---

项目脚本（package.json）

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

---

Vue 3 必装插件

插件	用途	什么时候用
@vitejs/plugin-vue	Vue 3 支持	Vue 项目必装，否则无法识别 .vue 文件
unplugin-auto-import	自动导入 API	当你的 Vue 组件中频繁 import { ref, computed } from 'vue' 时，此插件自动导入，减少样板代码
unplugin-vue-components	组件自动注册	不用手动 import 和 components 注册，模板中直接使用组件就会自动注册
vite-plugin-svg-icons	SVG 图标	把 SVG 文件打包成图标组件，方便在项目中使用 <svg-icon name="xxx" />
vite-plugin-mock	数据 mock	后端接口还没开发好时，用 mock 数据先开发前端，不被后端阻塞

插件安装示例

# 安装 Vue 3 支持插件
yarn add -D @vitejs/plugin-vue

# 安装自动导入插件
yarn add -D unplugin-auto-import unplugin-vue-components

# 安装 SVG 图标插件
yarn add -D vite-plugin-svg-icons

# 安装 Mock 插件
yarn add -D vite-plugin-mock

基础配置示例

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons'
import { viteMockServe } from 'vite-plugin-mock'
import path from 'path'

export default defineConfig({
  plugins: [
    vue(),  // Vue 3 支持
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],  // 自动导入这些 API
    }),
    Components({
      resolvers: [],  // 组件解析器
    }),
    createSvgIconsPlugin({
      iconDirs: [path.resolve(process.cwd(), 'src/icons/svg')],  // SVG 目录
    }),
    viteMockServe({
      mockPath: 'mock',  // mock 文件目录
    }),
  ],
})

---

常用配置

环境变量（.env 文件）

Vite 内置了 dotenv 支持，使用 .env 文件管理环境变量。完整用法详见 dotenv 常用命令。

# .env（所有环境生效）
VITE_API_URL=https://api.example.com

# .env.development（仅开发环境）
VITE_API_URL=http://localhost:3000

# .env.production（仅生产环境）
VITE_API_URL=https://api.example.com

⚠️ 只有以 VITE_ 开头的变量才会暴露给客户端。

在代码中使用：

console.log(import.meta.env.VITE_API_URL)
console.log(import.meta.env.MODE)        // development / production
console.log(import.meta.env.PROD)         // 是否是生产环境

指定构建模式：

# 使用 .env.staging 文件
vite build --mode staging

路径别名

为什么需要 fileURLToPath？ Vite 使用 ESM 模块系统，而 __dirname 是 CommonJS 的全局变量，在 ESM 中不可用。需要使用 fileURLToPath 将 import.meta.url 转换为文件路径，再通过 path.dirname 获取目录名。

// vite.config.ts
import { defineConfig } from 'vite'
import path from 'path'
import { fileURLToPath } from 'url'  // ESM 中获取文件路径

// 将 import.meta.url 转换为文件路径，再获取目录名
const __dirname = path.dirname(fileURLToPath(import.meta.url))

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),            // @ 指向 src 目录
      '@components': path.resolve(__dirname, 'src/components'),  // @components 指向组件目录
      '@utils': path.resolve(__dirname, 'src/utils'),  // @utils 指向工具目录
    },
  },
})

使用时：

import Button from '@/components/Button.vue'  // 使用别名导入组件
import { formatDate } from '@utils/date'      // 使用别名导入工具函数

开发代理（解决跨域）

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      // 简单代理
      '/api': 'http://localhost:3000',

      // 详细配置
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
})

前端请求 /api/users 会被代理到 http://localhost:3000/users。

---

Vue 3 + Vite 最佳实践

目录结构

src/
├── api/              # API 请求
├── assets/           # 静态资源
├── components/       # 公共组件
├── composables/      # 组合式函数
├── layouts/          # 布局组件
├── router/           # 路由配置
├── stores/           # Pinia 状态管理
├── styles/           # 全局样式
├── utils/            # 工具函数
├── views/            # 页面组件
├── App.vue           # 根组件
└── main.ts           # 入口文件

自动导入配置

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import AutoImport from 'unplugin-auto-import/vite'  // 自动导入插件
import Components from 'unplugin-vue-components/vite'  // 组件自动注册插件
import { ElementPlusResolver } from 'unplugin-vue-components/resolvers'  // Element Plus 解析器

export default defineConfig({
  plugins: [
    vue(),  // Vue 3 支持
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],  // 自动导入这些 API
      resolvers: [ElementPlusResolver()],  // Element Plus 按需导入
    }),
    Components({
      resolvers: [ElementPlusResolver()],  // Element Plus 组件按需导入
    }),
  ],
})

---

常见问题

开发服务器启动慢

// vite.config.ts
import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    include: ['vue', 'vue-router'],
  },
})

构建产物过大

# 使用 rollup-plugin-visualizer 分析
yarn add -D rollup-plugin-visualizer

# vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer'
export default {
  plugins: [visualizer()],
}

---

参考

• Vite 官方文档
• Vue 3 官方文档
• Vite GitHub