Vite 创建 Vue3 项目完整指南：从初始化到运行（附实操代码）

Vite 创建 Vue3 项目完整指南：从初始化到运行（附实操代码）

Vite 作为新一代前端构建工具，凭借 “即时热更新” 和 “零打包启动” 的特性，已成为 Vue3 项目开发的首选工具。相比传统的 Webpack，Vite 能大幅提升开发效率，尤其在大型项目中，启动时间可从分钟级缩短至秒级。本文将详细讲解使用 Vite 创建 Vue3 项目的完整流程，包括环境准备、项目初始化、目录结构解析、基础配置与运行优化，通过极简代码示例，帮助开发者快速搭建可用于生产的 Vue3 项目框架。

一、环境准备：安装核心依赖

使用 Vite 创建 Vue3 项目前，需确保本地环境已安装 Node.js，这是 Vite 运行的基础。

1. 检查 Node.js 版本

Vite 要求 Node.js 版本≥14.18.0 或 ≥16.0.0（推荐使用 16.x 或 18.x LTS 版本，稳定性更好）。打开终端执行以下命令检查版本：

node -v # 查看Node.js版本，需满足≥14.18.0

npm -v # 查看npm版本（通常随Node.js附带）

若版本不满足或未安装 Node.js，需先从Node.js 官网下载并安装对应版本（建议选择 “长期支持版 LTS”）。

2. 配置 npm 镜像（可选，提升下载速度）

国内用户直接使用 npm 官方源可能存在下载缓慢问题，可配置淘宝镜像（现更名为 “npmmirror”）：

# 配置npm镜像

npm config set registry https://registry.npmmirror.com

# 验证配置是否生效

npm config get registry # 输出https://registry.npmmirror.com即成功

二、项目创建：初始化 Vue3 项目

Vite 提供了两种创建 Vue3 项目的方式：通过npm create vite命令快速初始化，或使用 Vue 官方的create-vue工具（更适合生产级项目）。

1. 方式一：使用npm create vite快速创建（简易版）

这是最快捷的方式，适合快速搭建 demo 或小型项目：

# 执行创建命令，格式：npm create vite@latest 项目名 -- --template 模板类型

npm create vite@latest vue3-vite-demo -- --template vue

执行命令后，终端会提示确认项目名称和模板，按如下步骤操作：

1. 确认项目名称：默认是vue3-vite-demo，直接回车即可；

1. 选择框架：通过方向键选择Vue；

1. 选择变体：选择JavaScript（新手推荐）或TypeScript（类型安全，适合大型项目）。

创建完成后，进入项目目录并安装依赖：

# 进入项目目录

cd vue3-vite-demo

# 安装项目依赖

npm install

# 启动开发服务器

npm run dev

启动成功后，终端会显示访问地址（默认是http://localhost:5173/），打开浏览器即可看到 Vue3 默认页面。

2. 方式二：使用create-vue创建（生产级，推荐）

create-vue是 Vue 官方提供的项目脚手架，包含路由、Pinia、ESLint 等生产级配置，适合实际项目开发：

# 执行创建命令

npm create vue@latest

执行后需按提示完成配置选择（根据项目需求勾选，新手可参考以下推荐配置）：

• Project name（项目名）：输入vue3-vite-project；

• Add TypeScript?（是否添加 TypeScript）：选No（后续可按需添加）；

• Add JSX Support?（是否支持 JSX）：选No；

• Add Vue Router for Single Page Application development?（是否添加路由）：选Yes（单页应用必备）；

• Add Pinia for state management?（是否添加 Pinia 状态管理）：选Yes（替代 Vuex 的官方方案）；

• Add ESLint for code quality?（是否添加 ESLint 代码检查）：选Yes；

• Add Prettier for code formatting?（是否添加 Prettier 代码格式化）：选Yes。

配置完成后，按提示执行后续命令：

# 进入项目目录

cd vue3-vite-project

# 安装依赖

npm install

# 启动开发服务器

npm run dev

这种方式创建的项目包含完整的生产级配置，无需手动搭建路由、状态管理等基础框架，开箱即用。

三、项目目录结构解析

理解 Vite+Vue3 项目的目录结构，是后续开发的基础，以下以create-vue创建的项目为例（关键目录标注）：

vue3-vite-project/

├── node_modules/ # 项目依赖包（npm install生成）

├── public/ # 静态资源目录（不会被Vite处理）

│ └── favicon.ico # 浏览器标签图标

├── src/ # 项目核心代码目录

│ ├── assets/ # 静态资源（图片、样式等，会被Vite处理）

│ ├── components/ # 通用组件目录（如Button、Card等）

│ ├── router/ # 路由配置目录（含index.js路由定义）

│ ├── stores/ # Pinia状态管理目录（含counter.js示例）

│ ├── views/ # 页面组件目录（如Home.vue、About.vue）

│ ├── App.vue # 根组件（项目入口组件）

│ ├── main.js # 入口文件（初始化Vue实例、挂载路由等）

│ └── style.css # 全局样式文件

├── .eslintrc.cjs # ESLint配置文件

├── .prettierrc.json # Prettier配置文件

├── index.html # 入口HTML文件（Vite的特殊入口）

├── package.json # 项目配置文件（依赖、脚本命令等）

└── vite.config.js # Vite核心配置文件

核心文件说明：

• index.html：与传统项目不同，Vite 以 HTML 为入口，通过<script type="module" src="/src/main.js"></script>引入 JS 入口，无需 Webpack 的 entry 配置；

• vite.config.js：Vite 的核心配置文件，可配置服务器端口、代理、插件等；

• src/main.js：Vue 实例初始化入口，负责创建 App、使用路由和 Pinia，并挂载到 HTML 的 #app 元素上。

四、基础配置：定制 Vite 与 Vue3 项目

根据项目需求，需对 Vite 和 Vue3 项目进行基础配置，如修改端口、配置代理、设置全局样式等。

1. 修改 Vite 配置（vite.config.js）

Vite 的配置集中在vite.config.js，以下是常用配置示例：

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'

import vue from '@vitejs/plugin-vue'

export default defineConfig({

// 配置Vue插件（必选）

plugins: [vue()],

// 配置开发服务器

server: {

port: 8080, // 修改开发服务器端口（默认5173）

open: true, // 启动后自动打开浏览器

proxy: { // 配置接口代理（解决跨域问题）

'/api': {

target: 'http://localhost:3000', // 后端接口地址

changeOrigin: true, // 开启跨域

rewrite: (path) => path.replace(/^\/api/, '') // 移除/api前缀

}

}

},

// 配置路径别名（简化import路径）

resolve: {

alias: {

'@': fileURLToPath(new URL('./src', import.meta.url)) // @指向src目录

}

}

})

配置完成后，重启开发服务器（npm run dev）即可生效。

2. 全局样式配置（src/style.css）

在src/style.css中编写全局样式，会自动应用到所有组件：

/* src/style.css */

/* 全局样式重置 */

* {

margin: 0;

padding: 0;

box-sizing: border-box;

}

/* 全局字体设置 */

body {

font-family: 'Arial', sans-serif;

line-height: 1.6;

color: #333;

}

/* 全局组件样式（如按钮） */

.btn {

padding: 8px 16px;

border: none;

border-radius: 4px;

background: #42b983; /* Vue默认主题色 */

color: white;

cursor: pointer;

}

.btn:hover {

background: #359469;

}

在组件中可直接使用全局样式，无需额外导入：

<!-- src/components/Hello.vue -->

<template>

<button class="btn">全局样式按钮</button>

</template>

3. 路由配置（src/router/index.js）

create-vue已默认配置路由，若需添加新页面，只需修改src/router/index.js：

import { createRouter, createWebHistory } from 'vue-router'

import HomeView from '../views/HomeView.vue'

// 导入新页面组件

import NewPageView from '../views/NewPageView.vue'

const router = createRouter({

history: createWebHistory(import.meta.env.BASE_URL),

routes: [

{

path: '/',

name: 'home',

component: HomeView

},

{

path: '/about',

name: 'about',

component: () => import('../views/AboutView.vue') // 懒加载

},

// 添加新路由

{

path: '/new-page',

name: 'newPage',

component: NewPageView

}

]

})

export default router

五、项目运行与打包优化

开发完成后，需掌握项目的运行、打包与优化技巧，确保项目在生产环境中高效运行。

1. 开发环境运行

启动开发服务器的命令已在package.json中配置，直接执行：

# 启动开发服务器（热更新开启）

npm run dev

开发过程中，Vite 会监听文件变化，实时更新页面（热模块替换 HMR），无需手动刷新浏览器，大幅提升开发效率。

2. 生产环境打包

项目开发完成后，执行以下命令打包生产版本：

# 打包生产环境代码（输出到dist目录）

npm run build

打包完成后，dist目录中会生成优化后的静态文件（JS、CSS、HTML 等），可直接部署到 Nginx、Apache 等服务器。

3. 打包优化建议

• 分析打包体积：安装rollup-plugin-visualizer分析依赖体积，找出大文件：

# 安装依赖

npm install rollup-plugin-visualizer --save-dev

在vite.config.js中添加配置：

import { visualizer } from 'rollup-plugin-visualizer'

export default defineConfig({

plugins: [

vue(),

visualizer({ open: true }) // 打包后自动打开体积分析图

]

})

• 按需引入依赖：避免全量引入大型库（如 Element Plus），采用按需引入方式，减少打包体积；

• 压缩静态资源：Vite 默认已压缩 JS、CSS，可通过vite-plugin-imagemin进一步压缩图片：

npm install vite-plugin-imagemin --save-dev

在vite.config.js中配置：

import viteImagemin from 'vite-plugin-imagemin'

export default defineConfig({

plugins: [

vue(),

viteImagemin({

gifsicle: { optimizationLevel: 7 }, // GIF优化

optipng: { optimizationLevel: 7 }, // PNG优化

jpegtran: { quality: 80 } // JPG优化

})

]

})

六、常见问题与解决方案

在使用 Vite 创建 Vue3 项目过程中，可能遇到一些常见问题，以下是针对性解决方案。

1. 启动项目提示 “端口被占用”

原因：默认端口（5173）被其他程序占用。

解决：修改vite.config.js的server.port配置，更换未被占用的端口（如 8080、3000）。

2. 引入组件时路径报错

原因：未配置路径别名，或别名配置错误。

解决：确保vite.config.js中已配置@指向src目录，且导入时使用正确的别名：

// 正确导入（使用@别名）

import Hello from '@/components/Hello.vue'

// 错误导入（相对路径错误）

import Hello from '../components/Hello.vue' // 需根据文件层级调整

3. 热更新不生效

原因：可能是文件路径包含特殊字符，或 Vite 配置冲突。

解决：

1. 确保项目路径不含中文、空格等特殊字符；

1. 重启开发服务器（npm run dev）；

1. 检查vite.config.js是否有异常配置，可暂时注释自定义配置排查问题。

4. 打包后页面空白

原因：路由模式使用createWebHistory（history 模式），但服务器未配置重定向。

解决：

1. 开发阶段可暂时改用createWebHashHistory（hash 模式，URL 含 #）；

1. 生产环境需在服务器配置重定向（如 Nginx 添加try_files $uri $uri/ /index.html;）。

七、总结

使用 Vite 创建 Vue3 项目的核心流程可概括为：

1. 准备 Node.js 环境（≥14.18.0）；

1. 通过npm create vite或create-vue初始化项目；

1. 配置 Vite（端口、代理、别名等）；

1. 开发组件与页面；

1. 打包优化并部署。

Vite 的优势在于 “快”—— 零打包启动、即时热更新，大幅提升 Vue3 项目的开发体验；而create-vue则提供了生产级的项目骨架，减少基础配置工作量。无论是快速搭建 demo，还是开发大型生产项目，Vite+Vue3 都是当前前端开发的优选组合。

后续学习可重点关注：Vue3 组合式 API（如setup语法、ref/reactive）、Pinia 状态管理、Vite 插件开发等内容，这些知识将帮助你构建更复杂、高效的 Vue3 应用。