Vue3+Vite+TS项目快速搭建指南

在当今快速发展的前端领域，Vue 3 凭借其出色的性能优化和组合式 API 设计，成为众多开发者的首选框架。结合 Vite 的极速构建能力、TypeScript 的类型安全、Element-Plus 的丰富组件库以及 Pinia 的状态管理，这套技术栈能够高效支撑现代 Web 应用的开发需求。

Vite 作为新一代构建工具，显著提升了开发体验，其基于原生 ESM 的按需编译机制大幅缩短了启动和热更新时间。TypeScript 的引入增强了代码的可维护性和健壮性，而 Element-Plus 为界面开发提供了开箱即用的高质量组件。Pinia 作为 Vue 的轻量级状态管理方案，简化了复杂状态逻辑的组织与共享。

使用到的技术栈：Vue3 + Vite + TS + Element-Plus + Pinia

简单介绍各项技术：

Vue 3：组合式 API 与响应式系统的深度优化。
Vite：闪电般的构建与热更新速度。
TypeScript：类型检查与代码智能提示。
Element-Plus：企业级 UI 组件库。
Pinia：直观且类型友好的状态管理。

一、环境安装指南

1. 安装 Node.js

推荐使用 NVM（Node Version Manager）工具进行安装，能够帮助你：

管理多个 Node.js 版本
快速切换不同版本

NVM官方地址：NVM一个nodejs版本管理工具！

安装步骤：

① 下载并安装所需版本

② 安装完成后，在 NVM 安装目录中找到 settings.txt 文件，配置下载镜像

③ 配置环境变量：

右键点击"此电脑"
选择"属性" → "高级系统设置"

④ 打开命令窗口 (Win+R) 输入命令验证安装

⑤ 查看是否安装成功

输入命令：

nvm-v

⑥ 例如安装node20.20.0版本

输入命令：

nvm install 20.20.0

⑦ 查看所有nodejs版本

输入命令：

nvm list / ls

⑧ 切换nodejs版本

输入命令：

nvm use [版本号]

⑨ nvm基本使用指令

# 安装指定版本
nvm install [版本号]（如：nvm install 20.20.0）

# 查看已安装版本
nvm list 或 nvm ls

# 切换版本
nvm use [版本号]

# 其他常用指令
nvm -v        # 查看当前版本
nvm --config  # 查看配置
nvm on        # 开启 NVM
nvm off       # 关闭 NVM

2. 安装 VSCode

Visual Studio Code（VS Code）是一款由微软开发的免费、开源且跨平台的轻量级代码编辑器，支持多种编程语言和丰富的扩展插件。

vscode官方地址：The open source AI code editor

安装步骤：

① 点击安装windows版本，双击运行安装包安装即可

二、开始搭建项目

1.初始化项目

创建步骤：

① 进入到创建项目的目录下输入cmd回车进入命令行

② 输入使用vite初始化项目命令

npm create vite

③ 输入项目名称

④ 选择Vue

⑤ 选择TypeScript

⑥ 回车确认创建成功

三、运行并安装相关依赖

1.运行项目

运行步骤：

① 使用Vscode打开项目

② 输入安装node包依赖命令

npm install / i

③ 输入启动命令

npm run dev

④ 浏览器运行该地址

2.安装相关依赖

安装步骤：

① 安装路由

#我这里安装了Router4为了兼容vite版本
npm i vue-router@4  [@版本号]

在src目录下分别创建router和views文件夹，并且创建首页Home.vue和创建index.ts文件配置路由

// index.ts路由配置文件
import { createRouter, createWebHashHistory } from 'vue-router'

// 路由懒加载：按需加载首页组件，优化首屏性能
const HomePage = () => import('../views/Home.vue')

const router = createRouter({
    // 使用 hash 模式，路由格式为 /#/xxx，无需后端配置
    history: createWebHashHistory(),
    routes: [
        {
            path: '/',           // 根路径
            meta: { title: '首页' },  // 路由元信息，存储页面标题等额外数据
            component: HomePage  // 对应页面组件
        }
    ]
})

// 全局前置守卫：路由跳转前执行
router.beforeEach((to, from, next) => {
    // 可用于权限验证、登录检查等
    next()  // 必须调用 next() 才能继续导航
})

// 全局后置钩子：路由跳转完成后执行
router.afterEach((to, from) => {
    // 动态设置页面标题
    if (to.meta && to.meta.title) {
        document.title = to.meta.title as string
    }
})

export default router

在main.ts入口文件创建应用实例并挂载路由

// mian.ts入口文件
// 从 vue 核心库中导入 createApp 函数，用于创建 Vue 应用实例
import { createApp } from 'vue'

// 导入全局样式文件，通常包含 CSS 重置、通用样式、主题变量等
import './style.css'

// 导入根组件 App.vue，这是整个应用的顶层组件
import App from './App.vue'

// 导入路由配置，路由负责管理页面导航和 URL 映射
import router from './router'

// 创建 Vue 应用实例，传入根组件 App
const app = createApp(App)

// 将路由插件挂载到应用上，启用路由功能
// 之后所有组件都能通过 this.$router 和 this.$route 访问路由
app.use(router)

// 将应用挂载到 DOM 中的 #app 元素上
// 对应 index.html 中的 <div id="app"></div>
app.mount('#app')

② 安装pinia状态管理

npm i pinia

接着在main.ts入口文件创建应用实例

// mian.ts入口文件
// 从 vue 核心库中导入 createApp 函数，用于创建 Vue 应用实例
import { createApp } from 'vue'

// 导入全局样式文件，通常包含 CSS 重置、通用样式、主题变量等
import './style.css'

// 导入根组件 App.vue，这是整个应用的顶层组件
import App from './App.vue'

// 导入路由配置，路由负责管理页面导航和 URL 映射
import router from './router'

// 从 pinia 库中导入 createPinia 函数
// Pinia 是 Vue 3 官方推荐的状态管理库，用于跨组件共享数据
import { createPinia } from 'pinia'
const pinia = createPinia();

// 创建 Vue 应用实例，传入根组件 App
const app = createApp(App)

// 将路由插件挂载到应用上，启用路由功能
// 之后所有组件都能通过 this.$router 和 this.$route 访问路由
app.use(router)

// 将 Pinia 状态管理插件挂载到应用上
// 之后所有组件都能通过 this.$pinia 访问，或使用 useStore() 获取状态
app.use(pinia)

// 将应用挂载到 DOM 中的 #app 元素上
// 对应 index.html 中的 <div id="app"></div>
app.mount('#app')

并在src目录下，创建store文件夹放置所有状态管理，示例用户登录信息

// user.ts 用户信息状态管理文件
import { defineStore } from 'pinia'

export default defineStore('user', {
    state: () => ({
        token: localStorage.getItem('token') || '',
        userInfo: JSON.parse(localStorage.getItem('userInfo') || '{}')
    }),
    getters: {
        isLogin: (state) => !!state.token
    },
    actions: {
        // 更新用户信息的某个字段
        updateUserInfoField(key: string, value: any) {
            this.userInfo[key] = value;
            localStorage.setItem('userInfo', JSON.stringify(this.userInfo));
        },
        // 设置 token 和 userInfo
        setAuthData(token: string, userInfo: object) {
            this.token = token;
            this.userInfo = userInfo;
            // 存储userInfo，使用JSON.stringify()转换为字符串
            localStorage.setItem('token', token)
            localStorage.setItem('userInfo', JSON.stringify(userInfo));
        },
        // 清除登录数据
        clearAuthData() {
            this.token = '';
            this.userInfo = {};
            // 清除 token 和用户信息
            localStorage.removeItem('token');
            localStorage.removeItem('userInfo');
        },
    },
})

③ 安装axios

npm i axios

在src目录下，创建统一管理配置文件夹config，在config目录下创建统一管理后端api地址文件baseURL.ts

// baseURL.ts 统一管理后端api地址文件
// 这里的地址根据自己实际地址配置
// 开发环境 
export const baseURL_dev:string = 'http://localhost:8080/api/'

// 生产环境  
export const baseURL_pro:string = 'http://localhost:8080/api/'

// 测试环境
export const baseURL_test:string = 'http://localhost:8080/api/'

继续在src目录下，创建utils文件夹放置工具类文件，创建request.ts文件封装axios

// request.ts 文件封装axios
// 导入 axios 库，用于发送 HTTP 请求
import axios from 'axios'

// 导入基础请求地址配置，区分开发/测试/生产环境
import { baseURL_dev } from '../config/baseURL.ts'

// 创建 axios 实例，统一配置请求参数
const instance = axios.create({
    baseURL: baseURL_dev,           // 基础请求地址，所有请求会自动拼接该前缀
    timeout: 50000,                 // 请求超时时间，单位毫秒（50秒）
    headers: { 'X-Custom-Header': 'foobar' }  // 自定义请求头，可放通用标识等
})

// ==================== 请求拦截器 ====================
// 在请求发送前统一处理（如添加 token、加载动画等）
instance.interceptors.request.use(
    function (config) {
        // 在发送请求之前做些什么
        return config
    },
    function (error) {
        // 请求发送失败时处理
        return Promise.reject(error)
    }
)

// ==================== 响应拦截器 ====================
// 在接收到响应后统一处理（如错误提示、数据解构、token 过期跳转等）
instance.interceptors.response.use(
    function (response) {
        // 直接返回响应数据，后续可在拦截器中统一处理错误码
        return response
    },
    function (error) {
        // 对响应错误做点什么
        return Promise.reject(error)
    }
)

// ==================== 封装 HTTP 请求方法 ====================

// GET 请求：用于获取数据
// @param url 请求地址
// @param params 查询参数，会拼接在 URL 后面（如 ?id=1&name=xxx）
export const $get = async (url: string, params: object = {}) => {
    let { data } = await instance.get(url, { params })
    return data
}

// POST 请求：用于提交数据（如表单提交、创建资源）
// @param url 请求地址
// @param params 请求体数据，放在 body 中发送
export const $post = async (url: string, params: object = {}) => {
    let { data } = await instance.post(url, params)
    return data
}

// PUT 请求：用于更新数据（全量更新）
// @param url 请求地址
// @param params 请求体数据
export const $put = async (url: string, params: object = {}) => {
    let { data } = await instance.put(url, params)
    return data
}

// DELETE 请求：用于删除数据
// @param url 请求地址
// @param params 查询参数，部分后端也支持 body 传参
export const $delete = async (url: string, params: object = {}) => {
    let { data } = await instance.delete(url, { params })
    return data
}

示例拦截器对用户登录信息状态以及登录状态失效处理

// request.ts 文件封装axios
// 导入 axios 库，用于发送 HTTP 请求
import axios from 'axios'

// 导入基础请求地址配置，区分开发/测试/生产环境
import { baseURL_dev } from '../config/baseURL.ts'

// 导入 Element Plus 的消息提示组件，用于显示错误/成功提示
import { ElMessage } from 'element-plus'

// 导入用户状态管理 store，用于获取 token 和清除登录状态
import useAuthStore from '../store/user.ts'

// 创建 axios 实例，统一配置请求参数
const instance = axios.create({
    baseURL: baseURL_dev,           // 基础请求地址，所有请求会自动拼接该前缀
    timeout: 50000,                 // 请求超时时间，单位毫秒（50秒）
    headers: { 'X-Custom-Header': 'foobar' }  // 自定义请求头，可放通用标识等
})

// ==================== 请求拦截器 ====================
// 在请求发送前统一处理（如添加 token、加载动画等）
instance.interceptors.request.use(
    function (config) {
        // 获取用户认证 store，从中读取 token
        const authStore = useAuthStore()
        
        // 优先从 store 获取 token，若不存在则从 localStorage 读取
        // 支持页面刷新后 token 不丢失
        const token = authStore.token || localStorage.getItem('token')
        
        // 如果存在 token，添加到请求头中，供后端验证身份
        // PC_TOKEN 是后端约定的自定义请求头字段名
        if (token) {
            config.headers['PC_TOKEN'] = token
        }
        
        // 打印请求头，方便调试时查看 token 是否正确携带
        console.log(config.headers, "config.headers")
        
        // 返回处理后的配置，axios 将使用此配置发送请求
        return config
    },
    function (error) {
        // 请求发送失败（如网络断开、请求配置错误等）
        return Promise.reject(error)
    }
)

// ==================== 响应拦截器 ====================
// 在接收到响应后统一处理（如错误提示、数据解构、token 过期跳转等）
instance.interceptors.response.use(
    function (response) {
        // 请求成功，直接返回响应数据
        // 可在此统一解构数据，如 return response.data
        return response
    },
    function (error) {
        // 请求失败，判断是否有响应（有响应说明服务器返回了错误状态码）
        if (error.response) {
            // 从错误响应中提取状态信息
            const status = error.response.data
            
            // 如果返回 401 状态码，表示 token 过期或无效，需要重新登录
            if (status.code === 401) {
                // 弹出错误提示，告知用户登录已过期
                ElMessage.error('登录已过期，请重新登录')
                
                // 获取用户 store，清除本地保存的登录数据（token、用户信息等）
                const authStore = useAuthStore()
                authStore.clearAuthData()
                
                // 使用 window.location 进行页面跳转
                // 避免在拦截器中使用 Vue Router（可能因上下文问题导致异常）
                window.location.href = '/'
            }
        } else {
            // 没有响应（如网络断开、请求超时、CORS 错误等）
            ElMessage.error('请求失败，请检查网络')
        }
        
        // 将错误继续抛出，让调用方也能捕获并处理
        return Promise.reject(error)
    }
)

// ==================== 封装 HTTP 请求方法 ====================

// GET 请求：用于获取数据
// @param url 请求地址
// @param params 查询参数，会拼接在 URL 后面（如 ?id=1&name=xxx）
export const $get = async (url: string, params: object = {}) => {
    let { data } = await instance.get(url, { params })
    return data
}

// POST 请求：用于提交数据（如表单提交、创建资源）
// @param url 请求地址
// @param params 请求体数据，放在 body 中发送
export const $post = async (url: string, params: object = {}) => {
    let { data } = await instance.post(url, params)
    return data
}

// PUT 请求：用于更新数据（全量更新）
// @param url 请求地址
// @param params 请求体数据
export const $put = async (url: string, params: object = {}) => {
    let { data } = await instance.put(url, params)
    return data
}

// DELETE 请求：用于删除数据
// @param url 请求地址
// @param params 查询参数，部分后端也支持 body 传参
export const $delete = async (url: string, params: object = {}) => {
    let { data } = await instance.delete(url, { params })
    return data
}

继续在src目录下，创建api接口的二次封装文件，示例创建user.ts请求封装

// user.ts api请求封装
// 从封装好的请求工具中导入 $get 和 $post 方法
// 这些方法已配置好基础地址、超时、拦截器等通用逻辑
import { $get, $post } from '../utils/request.ts'

// ==================== 密码登录接口 ====================

/**
 * 密码登录请求封装
 * @param params 登录参数对象
 * @param params.username 用户名/账号
 * @param params.password 密码（建议后端接收前已做加密处理）
 * @returns 返回登录接口的响应数据，通常包含 token、用户信息等
 */
export const $pwdLogin = async (params: { username: string, password: string }) => {
    try {
        // 调用 POST 请求，向 /pc/user/pcLogin 接口提交登录信息
        const res = await $post('/pc/user/pcLogin', params);
        
        // 返回接口响应数据，调用方可从中提取 token 等登录凭证
        return res;
    } catch (error) {
        // 打印登录失败原因，便于开发调试
        console.error('登录失败:', error);
        
        // 将错误继续向上抛出，让调用方（如组件）决定如何处理
        // 例如：显示错误提示、记录日志、跳转页面等
        throw error;
    }
};

// ==================== 获取用户信息接口 ====================

/**
 * 根据用户ID获取用户信息
 * @param userId 用户唯一标识ID
 * @returns 返回用户详细信息，失败时返回 null
 */
export const $getUserInfo = async (userId: string) => {
    try {
        // 调用 GET 请求，将 userId 作为查询参数传递
        // 请求地址示例：/pc/user/getUserInfoById?userId=xxx
        const res = await $get('/pc/user/getUserInfoById', { userId });
        
        // 打印接口返回结果，方便开发阶段调试查看数据结构
        console.log('$getUserInfo 接口返回:', res);
        
        // 返回用户信息数据
        return res;
    } catch (error) {
        // 打印错误信息，提示获取用户信息失败
        console.error('获取用户信息失败:', error);
        
        // 返回 null 而非抛出错误，让调用方可以安全地判断数据是否存在
        // 适用于用户信息缺失不应阻断页面渲染的场景
        return null;
    }
};

④ 安装Element-Plus UI框架

npm i element-plus

继续在main.ts入口文件创建应用实例

// mian.ts入口文件
// 从 vue 核心库中导入 createApp 函数，用于创建 Vue 应用实例
import { createApp } from 'vue'

// 导入全局样式文件，通常包含 CSS 重置、通用样式、主题变量等
import './style.css'

// 导入根组件 App.vue，这是整个应用的顶层组件
import App from './App.vue'

// 导入路由配置，路由负责管理页面导航和 URL 映射
import router from './router'

// 从 pinia 库中导入 createPinia 函数
// Pinia 是 Vue 3 官方推荐的状态管理库，用于跨组件共享数据
import { createPinia } from 'pinia'
const pinia = createPinia();

// 导入 Element Plus UI 组件库及其样式
// Element Plus 是一套基于 Vue 3 的桌面端组件库，提供按钮、表单、表格等丰富组件
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

// 导入 Element Plus 的所有图标组件
// @element-plus/icons-vue 提供了一套常用的 SVG 图标
import * as ElementPlusIconsVue from '@element-plus/icons-vue'

// 创建 Vue 应用实例，传入根组件 App
const app = createApp(App)

// 将路由插件挂载到应用上，启用路由功能
// 之后所有组件都能通过 this.$router 和 this.$route 访问路由
app.use(router)

// 将 Pinia 状态管理插件挂载到应用上
// 之后所有组件都能通过 this.$pinia 访问，或使用 useStore() 获取状态
app.use(pinia)

// 将 Element Plus 组件库挂载到应用上
// 之后所有组件都可直接使用 el-button、el-table 等组件，无需单独导入
app.use(ElementPlus)

// 全局注册 Element Plus 的所有图标组件
// 遍历图标对象，将每个图标以组件形式注册到应用中
// 之后所有组件都可直接使用 <el-icon><Home /></el-icon> 或 <Home /> 方式引用图标
for (const [key, component] of Object.entries(ElementPlusIconsVue)) {
    app.component(key, component)
}

// 将应用挂载到 DOM 中的 #app 元素上
// 对应 index.html 中的 <div id="app"></div>
app.mount('#app')

顺手把原本公共样式格式化一下，这里看自己实际需求