Vue3+TypeScript+Vite企业级前端框架搭建指南-代码聚汇网

Vue3+TypeScript+Vite企业级前端框架搭建指南

斯迈尔齿科

1. 项目概述

在现代化前端开发中，Vue3 + TypeScript + Vite 的组合已经成为企业级应用开发的首选技术栈。结合 Element Plus UI 组件库和 Pinia 状态管理，可以构建出高性能、易维护的前端项目框架。本文将详细介绍如何从零开始搭建这样一个框架，并实现常见的布局结构。

2. 环境准备与项目初始化

2.1 创建Vite项目

首先确保你已经安装了Node.js（建议版本16+），然后通过以下命令创建Vite项目：

bash复制npm create vite@latest vue3-ts-element-template --template vue-ts

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

bash复制cd vue3-ts-element-template
npm install

2.2 安装必要依赖

我们需要安装Element Plus和Pinia：

bash复制npm install element-plus @element-plus/icons-vue pinia

同时安装Sass预处理器，以便使用SCSS语法：

bash复制npm install sass -D

3. 项目结构设计

3.1 目录结构规划

一个良好的项目结构应该遵循以下原则：

按功能模块划分
组件化思维
类型安全
易于维护

建议的项目结构如下：

code复制src/
├── assets/          # 静态资源
├── components/      # 公共组件
├── layout/          # 布局组件
├── router/          # 路由配置
├── store/           # Pinia状态管理
├── styles/          # 全局样式
├── utils/           # 工具函数
├── views/           # 页面视图
├── App.vue          # 根组件
└── main.ts          # 入口文件

4. 布局组件实现

4.1 基础布局结构

在src/layout目录下创建以下文件：

index.vue - 布局容器
Header.vue - 顶部导航
Aside.vue - 侧边菜单
Main.vue - 内容区域

4.1.1 布局容器 (index.vue)

vue复制<template>
  <el-container class="layout-container">
    <Header />
    <el-container class="content-container">
      <Aside />
      <Main />
    </el-container>
  </el-container>
</template>

<script setup lang="ts">
import Header from './Header.vue'
import Main from './Main.vue'
import Aside from './Aside.vue'
</script>

<style scoped lang="scss">
.layout-container {
  width: 100%;
  height: calc(100vh - 16px); // 16px 是 body的margin样式
  overflow: hidden;
  display: flex;
  flex-direction: column;

  :deep(.el-header) {
    padding: 0;
    flex-shrink: 0;
  }

  :deep(.el-aside) {
    overflow-y: auto;  // 侧边栏也可滚动
  }

  :deep(.el-main) {
    padding: 0;
    overflow-y: auto;  // 内容区域滚动
  }
}

.content-container {
  height: calc(100vh - 60px); // 减去 header 高度
  overflow: hidden;  // 容器本身不滚动
}
</style>

4.1.2 顶部导航 (Header.vue)

vue复制<template>
  <el-header class="header-layout">
    <div class="header-layout-content">
      <div class="header-left">
        <el-image src="/images/logo.png" alt=""></el-image>
        <h3>VUE3-ELEMENT-CESIUM</h3>
      </div>
      <div class="header-right">
        <el-popover
          trigger="click"
          :width="'auto'"
          popper-class="user-popover"
          popper-style="box-shadow: rgb(14 18 22 / 35%) 0px 10px 38px -10px, rgb(14 18 22 / 20%) 0px 10px 20px -15px; padding: 20px;"
        >
          <template #reference>
            <el-avatar
              :size="40"
              src="/images/user-icon.jpeg"
              style="margin-right: 20px"
            />
          </template>
          <template #default>
            <div class="popover-content">
              <a href="">个人中心</a>
              <a href="">退出登录</a>
            </div>
          </template>
        </el-popover>
      </div>
    </div>
  </el-header>
</template>

<script setup lang="ts">
// 这里可以添加用户相关的逻辑
</script>

<style scoped lang="scss">
.header-layout {
  width: 100%;
  height: 60px;
  box-sizing: border-box;
  padding: 0;
  flex-shrink: 0; // 防止被压缩
  background: #12A8F6;
  
  .header-layout-content {
    display: flex;
    justify-content: space-between;
    align-items: center;
    height: 100%;
    padding: 0 20px;
    
    .header-left {
      display: flex;
      align-items: center;
      gap: 10px;
      
      .el-image {
        width: 30px;
        height: 30px;
      }
      
      h3 {
        margin: 0;
        color: white;
      }
    }
    
    .header-right {
      display: flex;
      align-items: center;
    }
  }
}
</style>

4.1.3 侧边菜单 (Aside.vue)

vue复制<template>
  <el-aside class="aside-layout">
    <el-menu
      active-text-color="#ffd04b"
      background-color="#545c64"
      class="el-menu-vertical-demo"
      :default-active="route.path"
      text-color="#fff"
      :router="true"
      @open="handleOpen"
      @close="handleClose"
    >
      <template v-for="menuItem in menuList" :key="menuItem.id">
        <el-menu-item
          v-if="!menuItem.children || menuItem.children.length === 0"
          :index="menuItem.path"
        >
          <el-icon v-if="menuItem.icon">
            <component :is="menuItem.icon" />
          </el-icon>
          <span>{{ menuItem.meta?.title || menuItem.name }}</span>
        </el-menu-item>

        <el-sub-menu
          v-else
          :index="menuItem.id.toString()"
        >
          <template #title>
            <el-icon v-if="menuItem.icon">
              <component :is="menuItem.icon" />
            </el-icon>
            <span>{{ menuItem.meta?.title || menuItem.name }}</span>
          </template>

          <el-menu-item
            v-for="childItem in menuItem.children"
            :key="childItem.id"
            :index="childItem.path"
          >
            <el-icon v-if="childItem.icon">
              <component :is="childItem.icon" />
            </el-icon>
            <span>{{ childItem.meta?.title || childItem.name }}</span>
          </el-menu-item>
        </el-sub-menu>
      </template>
    </el-menu>
  </el-aside>
</template>

<script setup lang="ts">
import { useRoute } from "vue-router";
import { computed } from "vue";
import { useAccountStore } from "@/store/modules/account";

const route = useRoute();
const AccountStore = useAccountStore();

const menuList = computed(() => AccountStore.menu || [])

const handleOpen = (key: string, keyPath: string[]) => {
  console.log('菜单展开:', key, keyPath)
}

const handleClose = (key: string, keyPath: string[]) => {
  console.log('菜单收起:', key, keyPath)
}
</script>

<style scoped lang="scss">
.aside-layout {
  width: 200px;
  background: #122441;
  box-sizing: border-box;
  padding: 0;
  overflow-x: hidden;
  flex-shrink: 0;
  height: 100%;
}

:deep(.el-menu) {
  border: none;
  height: 100%;
  background-color: #545c64;
}

:deep(.el-menu-item.is-active) {
  background-color: #409eff !important;
}
</style>

4.1.4 内容区域 (Main.vue)

vue复制<template>
  <el-main class="main-layout">
    <router-view></router-view>
  </el-main>
</template>

<script setup lang="ts">
// 这里可以添加页面切换相关的逻辑
</script>

<style scoped lang="scss">
.main-layout {
  height: 100%;
  width: 100%;
  background: #f5f7fa;
  padding: 0;
  overflow-y: auto;     // 添加垂直滚动
  overflow-x: hidden;  // 隐藏水平滚动
}
</style>

4.2 样式优化与注意事项

Flex布局技巧：
- 使用flex-shrink: 0防止元素被压缩
- overflow: hidden配合overflow-y: auto实现局部滚动
- 使用calc()计算动态高度
Element Plus深度选择器：
- 使用:deep()修改组件库内部样式
- 避免直接修改组件库样式，优先使用props配置
响应式考虑：
- 使用相对单位(如vh、%)而非固定像素
- 考虑移动端适配方案

5. 状态管理与菜单配置

5.1 Pinia状态管理

创建account store来管理菜单和用户信息：

ts复制// src/store/modules/account.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

interface MenuItem {
  id: number
  path: string
  name: string
  meta?: {
    title: string
    icon?: string
  }
  children?: MenuItem[]
}

export const useAccountStore = defineStore('account', () => {
  const menu = ref<MenuItem[]>([])
  
  // 模拟从接口获取菜单
  const fetchMenu = async () => {
    // 实际项目中这里应该是API调用
    menu.value = [
      {
        id: 1,
        path: '/dashboard',
        name: 'Dashboard',
        meta: { title: '控制台', icon: 'Menu' }
      },
      {
        id: 2,
        path: '/user',
        name: 'User',
        meta: { title: '用户管理', icon: 'User' },
        children: [
          {
            id: 21,
            path: '/user/list',
            name: 'UserList',
            meta: { title: '用户列表' }
          },
          {
            id: 22,
            path: '/user/role',
            name: 'UserRole',
            meta: { title: '角色管理' }
          }
        ]
      }
    ]
  }

  return { menu, fetchMenu }
})

5.2 路由配置

结合Vue Router实现菜单路由：

ts复制// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import { useAccountStore } from '@/store/modules/account'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: [
    {
      path: '/',
      redirect: '/dashboard'
    },
    {
      path: '/login',
      name: 'Login',
      component: () => import('@/views/Login.vue')
    },
    {
      path: '/dashboard',
      name: 'Dashboard',
      component: () => import('@/views/Dashboard.vue'),
      meta: { requiresAuth: true }
    }
    // 其他路由...
  ]
})

// 路由守卫
router.beforeEach(async (to, from, next) => {
  const accountStore = useAccountStore()
  
  if (to.meta.requiresAuth) {
    // 检查登录状态
    if (!accountStore.isLoggedIn) {
      return next('/login')
    }
    
    // 获取菜单数据
    if (accountStore.menu.length === 0) {
      await accountStore.fetchMenu()
    }
  }
  
  next()
})

export default router

6. 常见问题与解决方案

6.1 菜单高亮问题

问题描述：当路由路径与菜单路径不完全匹配时，菜单项不会自动高亮。

解决方案：

ts复制// 在Aside.vue中修改default-active的计算方式
const activeMenu = computed(() => {
  const { path } = route
  // 查找匹配的菜单项
  const findActive = (menus: MenuItem[]): string => {
    for (const menu of menus) {
      if (menu.path === path) return menu.path
      if (menu.children) {
        const childPath = findActive(menu.children)
        if (childPath) return childPath
      }
    }
    return ''
  }
  return findActive(menuList.value) || path
})

6.2 样式冲突问题

问题描述：全局样式影响组件库样式，或组件库样式不符合需求。

解决方案：

使用scoped样式限制作用域
创建src/styles/element/index.scss覆盖默认变量：

scss复制// 主题色变量
$--color-primary: #12A8F6;

// 引入Element Plus样式
@use "element-plus/theme-chalk/src/index" as *;

6.3 性能优化建议

组件懒加载：

ts复制// 路由配置中使用动态导入
component: () => import('@/views/UserList.vue')

图标按需加载：

ts复制// 只导入使用的图标
import { Menu, User } from '@element-plus/icons-vue'

Pinia持久化：
使用pinia-plugin-persistedstate插件保持状态持久化：

bash复制npm install pinia-plugin-persistedstate

7. 项目集成与扩展

7.1 集成Axios

安装axios并创建请求拦截器：

bash复制npm install axios

ts复制// src/utils/request.ts
import axios from 'axios'

const service = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
})

// 请求拦截器
service.interceptors.request.use(config => {
  const accountStore = useAccountStore()
  if (accountStore.token) {
    config.headers.Authorization = `Bearer ${accountStore.token}`
  }
  return config
})

// 响应拦截器
service.interceptors.response.use(
  response => response.data,
  error => {
    if (error.response.status === 401) {
      // 处理未授权
      router.push('/login')
    }
    return Promise.reject(error)
  }
)

export default service

7.2 环境变量配置

创建.env和.env.development文件：

code复制# .env
VITE_API_BASE_URL=/api
VITE_APP_TITLE=My App

# .env.development
VITE_API_BASE_URL=http://localhost:3000/api

7.3 代码规范与质量

集成ESLint + Prettier：

bash复制npm install eslint eslint-plugin-vue @typescript-eslint/parser @typescript-eslint/eslint-plugin prettier eslint-config-prettier -D

创建.eslintrc.js：

js复制module.exports = {
  root: true,
  env: {
    node: true
  },
  extends: [
    'plugin:vue/vue3-essential',
    'eslint:recommended',
    '@vue/typescript/recommended',
    'plugin:prettier/recommended'
  ],
  rules: {
    'vue/multi-word-component-names': 'off'
  }
}

创建.prettierrc：

json复制{
  "semi": false,
  "singleQuote": true,
  "printWidth": 100,
  "trailingComma": "none",
  "arrowParens": "avoid"
}

8. 项目部署与优化

8.1 构建生产版本

bash复制npm run build

8.2 部署配置

Nginx配置示例：

nginx复制server {
  listen 80;
  server_name yourdomain.com;
  
  location / {
    root /path/to/dist;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
  
  location /api {
    proxy_pass http://backend:3000;
    proxy_set_header Host $host;
  }
}

CDN加速：

将静态资源上传至CDN
修改vite配置：

ts复制// vite.config.ts
export default defineConfig({
  build: {
    assetsDir: 'static',
    rollupOptions: {
      output: {
        chunkFileNames: 'static/js/[name]-[hash].js',
        entryFileNames: 'static/js/[name]-[hash].js',
        assetFileNames: 'static/[ext]/[name]-[hash].[ext]'
      }
    }
  }
})

8.3 性能监控

集成Sentry进行错误监控：

bash复制npm install @sentry/vue @sentry/tracing

ts复制// main.ts
import * as Sentry from '@sentry/vue'
import { Integrations } from '@sentry/tracing'

Sentry.init({
  app,
  dsn: 'your-dsn',
  integrations: [
    new Integrations.BrowserTracing({
      routingInstrumentation: Sentry.vueRouterInstrumentation(router),
      tracingOrigins: ['localhost', 'yourdomain.com']
    })
  ],
  tracesSampleRate: 1.0
})

9. 项目维护与迭代建议

组件文档化：

使用Storybook或VitePress编写组件文档
为每个组件添加Props、Events、Slots的说明

Git工作流：

采用Git Flow或Trunk Based Development
使用commitlint规范提交信息

自动化测试：

单元测试：Vitest + Vue Test Utils
E2E测试：Cypress或Playwright

持续集成：

GitHub Actions或GitLab CI
自动化构建、测试和部署

10. 总结与个人实践心得

在实际项目开发中，我总结了以下几点经验：

类型安全优先：

为所有接口定义TypeScript类型
使用泛型封装API请求
为Vue组件定义Props类型

状态管理分层：

全局状态使用Pinia管理
组件间状态使用provide/inject
复杂表单状态使用useForm等组合式函数

性能优化实践：

使用v-memo优化大型列表
合理使用keep-alive缓存路由
按需加载第三方库

错误处理策略：

全局错误边界组件
API错误统一处理
用户操作友好提示

这个框架在实际项目中已经过多次迭代，能够满足大多数中后台管理系统的需求。根据具体项目特点，可以灵活调整架构设计，比如添加微前端支持或集成可视化库等。