Vue3 核心工具安装及项目基础搭建完整版

本文以2026年最新生态为基础，从零开始搭建一个完整的企业级 Vue3 项目，涵盖环境准备、VS Code 插件配置、脚手架工具、路由配置、状态管理、UI 组件库、HTTP 请求封装等核心模块。

核心步骤概览

一、开发环境准备

1.1 安装 Node.js

Vue3 项目需要 Node.js 18.3 或更高版本。访问 Node.js 官网 下载并安装 LTS 版本（长期支持版本）。安装完成后，在终端验证：

bash

node -v   # 应显示 v18.3.0 或更高
npm -v    # 查看 npm 版本

1.2 VS Code 必备插件（三件套）

⚠️ 重要提醒：新项目一律使用 create-vue，vue-cli 已进入维护模式，不支持 Vue 3.4+ 的新特性。

使用 VS Code 开发 Vue3 应用，必须安装以下三个插件：

安装完成后，打开 .vue 文件，右下角应显示 "Vue (Volar)" 而非 "HTML" 或 "Vue (Vetur)"。

二、创建 Vue3 项目（官方推荐方式）

2.1 使用 create-vue 脚手架

create-vue 是 Vue 官方推荐的现代化项目脚手架工具，专为 Vue 3 设计，基于 Vite 构建。运行以下命令：

bash

npm create vue@latest

首次运行时会提示是否安装 create-vue 包，输入 y 或直接回车即可。

2.2 交互式配置（关键步骤）

运行后进入交互式配置界面，各选项说明如下：

💡 建议按需勾选，不要全选。例如暂不需要测试功能时可不勾选 Vitest 和 E2E，避免生成冗余配置。

2.3 安装依赖并启动项目

bash

cd my-project          # 进入项目目录
npm install            # 安装依赖
npm run dev            # 启动开发服务器

开发服务器启动后，在浏览器访问 http://localhost:5173 查看项目运行效果。

2.4 项目目录结构说明

text

my-project/
├── public/              # 静态资源（不会被 Vite 处理，直接复制到输出目录）
├── src/                 # 业务代码核心目录
│   ├── assets/          # 静态资源（会被 Vite 处理、压缩、哈希化）
│   ├── components/      # 可复用的 Vue 组件
│   ├── router/          # 路由配置
│   ├── stores/          # Pinia 状态管理
│   ├── views/           # 页面级组件（路由组件）
│   ├── App.vue          # 根组件
│   └── main.ts          # 入口文件
├── .env.development     # 开发环境配置文件
├── .env.production      # 生产环境配置文件
├── .eslintrc.js         # ESLint 配置文件
├── .prettierrc          # Prettier 配置文件
├── index.html           # HTML 入口模板
├── package.json         # 项目依赖清单
├── tsconfig.json        # TypeScript 配置文件
├── vite.config.ts       # Vite 核心配置文件
└── .gitignore           # Git 忽略文件清单

三、核心工具安装与配置

3.1 Vue Router 4（路由配置）

Vue 3 必须搭配 Vue Router 4.x 版本。如果创建项目时未勾选 Router，可手动安装：

bash

npm install vue-router@4

路由配置文件：在 src/router/index.ts 中定义路由规则：

typescript

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'

// 定义路由规则
const routes = [
  {
    path: '/',
    name: 'Home',
    component: () => import('../views/Home.vue')  // 路由懒加载
  },
  {
    path: '/about',
    name: 'About',
    component: () => import('../views/About.vue')
  }
]

// 创建路由实例
const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

export default router

在入口文件注册：src/main.ts：

typescript

import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

const app = createApp(App)
app.use(router)
app.mount('#app')

在组件中使用（App.vue）：

vue

<template>
  <!-- 导航链接 -->
  <router-link to="/">首页</router-link>
  <router-link to="/about">关于</router-link>
  <!-- 路由出口：匹配到的组件将渲染在此处 -->
  <router-view />
</template>

💡 Vue3 路由核心变化：不再使用 new VueRouter()，改用 createRouter()；路由模式从 mode: 'history' 改为 history: createWebHistory()；新增 useRouter() 和 useRoute() 钩子。

3.2 Pinia（状态管理）

Pinia 是 Vue 官方新一代状态管理库，已替代 Vuex，专为 Vue 3 设计。核心优势：语法简洁（无需 mutation）、天然支持 TypeScript、模块化设计。

安装 Pinia（如果创建项目时未勾选）：

bash

npm install pinia

在 src/main.ts 中全局注册：

typescript

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const app = createApp(App)
app.use(createPinia())  // 挂载 Pinia
app.mount('#app')

定义 Store（在 src/stores/user.ts 中）：

typescript

// src/stores/user.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  // 状态
  state: () => ({
    name: '张三',
    age: 20,
    token: ''
  }),
  // 计算属性
  getters: {
    doubleAge: (state) => state.age * 2
  },
  // 方法（支持同步/异步）
  actions: {
    updateName(newName: string) {
      this.name = newName
    },
    async login(account: string, pwd: string) {
      const res = await fetch('/api/login', { method: 'POST', body: JSON.stringify({ account, pwd }) })
      this.token = await res.json()
    }
  }
})

在组件中使用：

vue

<script setup>
import { storeToRefs } from 'pinia'
import { useUserStore } from '@/stores/user'

const userStore = useUserStore()
// 使用 storeToRefs 解构 state，保持响应式
const { name, age, doubleAge } = storeToRefs(userStore)
// actions 可直接解构
const { updateName, login } = userStore
</script>

<template>
  <p>姓名：{{ name }}</p>
  <p>年龄：{{ age }}</p>
  <p>双倍年龄：{{ doubleAge }}</p>
  <button @click="updateName('李四')">改名</button>
</template>

⚠️ 注意：直接解构 state 会丢失响应式，必须使用 storeToRefs。

3.3 Element Plus（UI 组件库）

Element Plus 是基于 Vue 3 的桌面端组件库。

安装：

bash

npm install element-plus --save

全局引入（完整引入） ：在 src/main.ts 中：

typescript

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

按需引入（推荐，减少打包体积） ：需安装 unplugin-vue-components 和 unplugin-auto-import：

bash

npm install -D unplugin-vue-components unplugin-auto-import

在 vite.config.ts 中配置：

typescript

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'

export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [ElementPlusResolver()]
    }),
    Components({
      resolvers: [ElementPlusResolver()]
    })
  ]
})

配置完成后，组件可直接在模板中使用，无需手动引入：

vue

<template>
  <el-button type="primary">主要按钮</el-button>
</template>

3.4 Axios（HTTP 请求封装）

Axios 是前端最主流的 HTTP 客户端库。推荐在 src/utils/request.ts 中集中封装。

安装：

bash

npm install axios

封装请求实例（src/utils/request.ts） ：

typescript

import axios, { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse } from 'axios'

// 从环境变量读取基础 URL
const BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api'

// 创建 axios 实例
const request: AxiosInstance = axios.create({
  baseURL: BASE_URL,
  timeout: 10000,
  headers: {
    'Content-Type': 'application/json;charset=utf-8'
  }
})

// 请求拦截器：统一添加 Token
request.interceptors.request.use(
  (config: InternalAxiosRequestConfig) => {
    const token = localStorage.getItem('access_token')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  },
  (error) => Promise.reject(error)
)

// 响应拦截器：统一处理错误
request.interceptors.response.use(
  (response: AxiosResponse) => {
    // 可根据业务状态码做统一处理
    if (response.data?.code !== 0) {
      console.error('业务错误:', response.data?.message)
      return Promise.reject(response.data)
    }
    return response.data
  },
  (error) => {
    console.error('请求错误:', error.message)
    return Promise.reject(error)
  }
)

export default request

使用示例（在 src/api/user.ts 中定义接口）：

typescript

import request from '@/utils/request'

export const userApi = {
  login(data: { account: string; pwd: string }) {
    return request.post('/login', data)
  },
  getUserInfo() {
    return request.get('/user/info')
  }
}

💡 环境变量配置：在 .env.development 和 .env.production 中配置 VITE_API_BASE_URL，区分开发/生产环境。

四、vite.config.ts 核心配置（2026 最佳实践）

typescript

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

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')  // 路径别名
    }
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',   // 后端服务地址
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router', 'pinia']  // 将公共库单独打包
        }
      }
    },
    terserOptions: {
      compress: {
        drop_console: true,   // 生产环境移除 console
        drop_debugger: true
      }
    }
  }
})

配置说明：

• 路径别名：配置 @ 指向 src，避免 ../../../ 的相对路径地狱

• 代理配置：解决开发环境跨域问题

• 代码分割：将公共库（vue、vue-router、pinia）单独打包，优化首屏加载

• 生产优化：移除 console 和 debugger，减小打包体积

五、总结：完整命令速查

以上配置构建了一个完整的 Vue3 企业级项目基础框架，涵盖开发环境、构建工具、路由、状态管理、UI 组件库和 HTTP 请求层，可直接在此基础上进行业务开发。