Vue 3 + TypeScript 现代前端开发最佳实践（2025版指南）

每日激励： “如果没有天赋，那就一直重复”

🌟 Hello，我是蒋星熠Jaxonic！
🌈 在浩瀚无垠的技术宇宙中，我是一名执着的星际旅人，用代码绘制探索的轨迹。
🚀 每一个算法都是我点燃的推进器，每一行代码都是我航行的星图。
🔭 每一次性能优化都是我的天文望远镜，每一次架构设计都是我的引力弹弓。
🎻 在数字世界的协奏曲中，我既是作曲家也是首席乐手。让我们携手，在二进制星河中谱写属于极客的壮丽诗篇！

摘要

Vue 3与TypeScript的完美结合，不仅代表着现代前端开发的技术巅峰，更是推动整个前端生态向类型安全、高性能、可维护性方向发展的重要里程碑。

在我参与的众多企业级前端项目中，Vue 3 + TypeScript技术栈的采用往往伴随着开发效率的显著提升和代码质量的大幅改善。从最初的Options API到Composition API的转变，从JavaScript到TypeScript的迁移，每一次技术升级都让我深刻感受到现代前端开发的强大威力。特别是Vue 3.3版本的发布，其在TypeScript支持、性能优化、开发体验等方面的增强，为我们构建更加稳定、高效的前端应用提供了坚实的技术保障。

Vue 3的Composition API彻底改变了我们组织和复用逻辑的方式。相比传统的Options API，Composition API提供了更好的类型推导、更灵活的逻辑组合以及更强的代码复用能力。在我最近负责的一个大型电商前端项目中，通过Composition API重构，代码复用率提升了60%，类型安全覆盖率达到95%以上，开发团队的协作效率显著提升。

TypeScript作为JavaScript的超集，其静态类型检查、智能代码提示、重构支持等特性，为大型前端项目的开发和维护提供了强有力的保障。特别是在团队协作场景中，TypeScript的类型约束能够有效减少接口对接错误，提升代码的可读性和可维护性。

在性能优化方面，Vue 3的响应式系统重写、Tree-shaking支持、Fragment特性等改进，让我们能够构建出更加轻量、高效的前端应用。结合Vite构建工具的极速热更新和现代化的开发体验，整个开发流程变得更加流畅和高效。

本文将从实战角度出发，深入探讨Vue 3 + TypeScript在现代前端开发中的最佳实践。我将结合真实的业务场景，通过详细的代码示例、架构设计以及性能优化方案，为大家呈现一个完整的现代前端开发解决方案。

1. 项目架构与环境搭建

1.1 Vite + Vue 3 + TypeScript项目初始化

# 创建Vue 3 + TypeScript项目
npm create vue@latest my-vue-app

# 选择配置选项
✔ Add TypeScript? … Yes
✔ Add JSX Support? … Yes
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
✔ Add Vitest for Unit Testing? … Yes
✔ Add an End-to-End Testing Solution? › Playwright
✔ Add ESLint for code quality? … Yes
✔ Add Prettier for code formatting? … Yes

cd my-vue-app
npm install

1.2 项目结构设计

src/
├── api/                    # API接口层
│   ├── modules/           # 按模块划分的API
│   ├── types/             # API类型定义
│   └── request.ts         # 请求封装
├── assets/                # 静态资源
│   ├── images/
│   ├── styles/
│   └── fonts/
├── components/            # 公共组件
│   ├── base/             # 基础组件
│   ├── business/         # 业务组件
│   └── layout/           # 布局组件
├── composables/          # 组合式函数
├── directives/           # 自定义指令
├── hooks/                # 自定义钩子
├── layouts/              # 页面布局
├── plugins/              # 插件配置
├── router/               # 路由配置
├── stores/               # 状态管理
├── types/                # 类型定义
├── utils/                # 工具函数
├── views/                # 页面组件
└── main.ts               # 入口文件

1.3 TypeScript配置优化

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/components/*": ["src/components/*"],
      "@/utils/*": ["src/utils/*"],
      "@/api/*": ["src/api/*"],
      "@/types/*": ["src/types/*"]
    }
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.d.ts",
    "src/**/*.tsx",
    "src/**/*.vue"
  ],
  "references": [{ "path": "./tsconfig.node.json" }]
}

2. Composition API最佳实践

2.1 响应式数据管理

// composables/useUserManagement.ts
import { ref, reactive, computed, watch } from 'vue'
import type { User, UserFilter, UserListResponse } from '@/types/user'
import { userApi } from '@/api/modules/user'

export interface UseUserManagementOptions {
  autoLoad?: boolean
  pageSize?: number
}

export function useUserManagement(options: UseUserManagementOptions = {}) {
  const { autoLoad = true, pageSize = 20 } = options

  // 响应式状态
  const loading = ref(false)
  const users = ref<User[]>([])
  const total = ref(0)
  const currentPage = ref(1)
  
  // 响应式对象
  const filter = reactive<UserFilter>({
    keyword: '',
    status: undefined,
    role: undefined,
    dateRange: undefined
  })

  // 计算属性
  const hasUsers = computed(() => users.value.length > 0)
  const totalPages = computed(() => Math.ceil(total.value / pageSize))
  const isEmpty = computed(() => !loading.value && !hasUsers.value)

  // 获取用户列表
  const fetchUsers = async (page = 1) => {
    try {
      loading.value = true
      currentPage.value = page

      const params = {
        page,
        pageSize,
        ...filter
      }

      const response: UserListResponse = await userApi.getUsers(params)
      
      users.value = response.data
      total.value = response.total
      
      return response
    } catch (error) {
      console.error('获取用户列表失败:', error)
      throw error
    } finally {
      loading.value = false
    }
  }

  // 创建用户
  const createUser = async (userData: Omit<User, 'id' | 'createdAt' | 'updatedAt'>) => {
    try {
      const newUser = await userApi.createUser(userData)
      users.value.unshift(newUser)
      total.value += 1
      return newUser
    } catch (error) {
      console.error('创建用户失败:', error)
      throw error
    }
  }

  // 更新用户
  const updateUser = async (id: string, userData: Partial<User>) => {
    try {
      const updatedUser = await userApi.updateUser(id, userData)
      const index = users.value.findIndex(user => user.id === id)
      if (index !== -1) {
        users.value[index] = updatedUser
      }
      return updatedUser
    } catch (error) {
      console.error('更新用户失败:', error)
      throw error
    }
  }

  // 删除用户
  const deleteUser = async (id: string) => {
    try {
      await userApi.deleteUser(id)
      const index = users.value.findIndex(user => user.id === id)
      if (index !== -1) {
        users.value.splice(index, 1)
        total.value -= 1
      }
    } catch (error) {
      console.error('删除用户失败:', error)
      throw error
    }
  }

  // 重置筛选条件
  const resetFilter = () => {
    Object.assign(filter, {
      keyword: '',
      status: undefined,
      role: undefined,
      dateRange: undefined
    })
  }

  // 监听筛选条件变化
  watch(
    () => ({ ...filter }),
    () => {
      currentPage.value = 1
      fetchUsers(1)
    },
    { deep: true }
  )

  // 自动加载数据
  if (autoLoad) {
    fetchUsers()
  }

  return {
    // 状态
    loading: readonly(loading),
    users: readonly(users),
    total: readonly(total),
    currentPage: readonly(currentPage),
    filter,
    
    // 计算属性
    hasUsers,
    totalPages,
    isEmpty,
    
    // 方法
    fetchUsers,
    createUser,
    updateUser,
    deleteUser,
    resetFilter
  }
}

2.2 自定义Hook封装

// hooks/useRequest.ts
import { ref, unref } from 'vue'
import type { Ref } from 'vue'

export interface UseRequestOptions<T> {
  immediate?: boolean
  onSuccess?: (data: T) => void
  onError?: (error: Error) => void
  loadingDelay?: number
}

export function useRequest<T = any, P extends any[] = any[]>(
  requestFn: (...args: P) => Promise<T>,
  options: UseRequestOptions<T> = {}
) {
  const {
    immediate = false,
    onSuccess,
    onError,
    loadingDelay = 0
  } = options

  const data = ref<T>()
  const loading = ref(false)
  const error = ref<Error>()

  let loadingTimer: NodeJS.Timeout | null = null

  const execute = async (...args: P): Promise<T | undefined> => {
    try {
      error.value = undefined

      // 延迟显示loading
      if (loadingDelay > 0) {
        loadingTimer = setTimeout(() => {
          loading.value = true
        }, loadingDelay)
      } else {
        loading.value = true
      }

      const result = await requestFn(...args)
      data.value = result
      
      onSuccess?.(result)
      return result
    } catch (err) {
      const errorObj = err instanceof Error ? err : new Error(String(err))
      error.value = errorObj
      onError?.(errorObj)
      throw errorObj
    } finally {
      if (loadingTimer) {
        clearTimeout(loadingTimer)
        loadingTimer = null
      }
      loading.value = false
    }
  }

  if (immediate) {
    execute()
  }

  return {
    data: data as Ref<T | undefined>,
    loading: readonly(loading),
    error: readonly(error),
    execute
  }
}

// hooks/useLocalStorage.ts
import { ref, watch, Ref } from 'vue'

export function useLocalStorage<T>(
  key: string,
  defaultValue: T,
  options: {
    serializer?: {
      read: (value: string) => T
      write: (value: T) => string
    }
  } = {}
): [Ref<T>, (value: T) => void, () => void] {
  const {
    serializer = {
      read: JSON.parse,
      write: JSON.stringify
    }
  } = options

  const storedValue = localStorage.getItem(key)
  const initialValue = storedValue !== null 
    ? serializer.read(storedValue) 
    : defaultValue

  const state = ref<T>(initialValue)

  const setValue = (value: T) => {
    try {
      state.value = value
      localStorage.setItem(key, serializer.write(value))
    } catch (error) {
      console.error(`Error setting localStorage key "${key}":`, error)
    }
  }

  const removeValue = () => {
    try {
      localStorage.removeItem(key)
      state.value = defaultValue
    } catch (error) {
      console.error(`Error removing localStorage key "${key}":`, error)
    }
  }

  // 监听状态变化，自动同步到localStorage
  watch(
    state,
    (newValue) => {
      setValue(newValue)
    },
    { deep: true }
  )

  return [state, setValue, removeValue]
}

3. 组件设计与类型安全

3.1 基础组件设计

<!-- components/base/BaseButton.vue -->
<template>
  <button
    :class="buttonClasses"
    :disabled="disabled || loading"
    :type="nativeType"
    @click="handleClick"
  >
    <BaseIcon v-if="loading" name="loading" class="animate-spin mr-2" />
    <BaseIcon v-else-if="icon" :name="icon" class="mr-2" />
    <slot />
  </button>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import BaseIcon from './BaseIcon.vue'

export interface BaseButtonProps {
  type?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'
  size?: 'small' | 'medium' | 'large'
  variant?: 'solid' | 'outline' | 'ghost' | 'link'
  disabled?: boolean
  loading?: boolean
  icon?: string
  nativeType?: 'button' | 'submit' | 'reset'
  block?: boolean
  round?: boolean
}

export interface BaseButtonEmits {
  click: [event: MouseEvent]
}

const props = withDefaults(defineProps<BaseButtonProps>(), {
  type: 'primary',
  size: 'medium',
  variant: 'solid',
  nativeType: 'button',
  disabled: false,
  loading: false,
  block: false,
  round: false
})

const emit = defineEmits<BaseButtonEmits>()

const buttonClasses = computed(() => {
  const classes = [
    'inline-flex items-center justify-center font-medium transition-colors',
    'focus:outline-none focus:ring-2 focus:ring-offset-2',
    'disabled:opacity-50 disabled:cursor-not-allowed'
  ]

  // 尺寸样式
  const sizeClasses = {
    small: 'px-3 py-1.5 text-sm',
    medium: 'px-4 py-2 text-base',
    large: 'px-6 py-3 text-lg'
  }
  classes.push(sizeClasses[props.size])

  // 类型和变体样式
  const typeVariantClasses = {
    primary: {
      solid: 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500',
      outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
      ghost: 'text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
      link: 'text-blue-600 hover:text-blue-700 underline focus:ring-blue-500'
    },
    secondary: {
      solid: 'bg-gray-600 text-white hover:bg-gray-700 focus:ring-gray-500',
      outline: 'border-2 border-gray-600 text-gray-600 hover:bg-gray-50 focus:ring-gray-500',
      ghost: 'text-gray-600 hover:bg-gray-50 focus:ring-gray-500',
      link: 'text-gray-600 hover:text-gray-700 underline focus:ring-gray-500'
    },
    success: {
      solid: 'bg-green-600 text-white hover:bg-green-700 focus:ring-green-500',
      outline: 'border-2 border-green-600 text-green-600 hover:bg-green-50 focus:ring-green-500',
      ghost: 'text-green-600 hover:bg-green-50 focus:ring-green-500',
      link: 'text-green-600 hover:text-green-700 underline focus:ring-green-500'
    },
    warning: {
      solid: 'bg-yellow-600 text-white hover:bg-yellow-700 focus:ring-yellow-500',
      outline: 'border-2 border-yellow-600 text-yellow-600 hover:bg-yellow-50 focus:ring-yellow-500',
      ghost: 'text-yellow-600 hover:bg-yellow-50 focus:ring-yellow-500',
      link: 'text-yellow-600 hover:text-yellow-700 underline focus:ring-yellow-500'
    },
    danger: {
      solid: 'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500',
      outline: 'border-2 border-red-600 text-red-600 hover:bg-red-50 focus:ring-red-500',
      ghost: 'text-red-600 hover:bg-red-50 focus:ring-red-500',
      link: 'text-red-600 hover:text-red-700 underline focus:ring-red-500'
    },
    info: {
      solid: 'bg-cyan-600 text-white hover:bg-cyan-700 focus:ring-cyan-500',
      outline: 'border-2 border-cyan-600 text-cyan-600 hover:bg-cyan-50 focus:ring-cyan-500',
      ghost: 'text-cyan-600 hover:bg-cyan-50 focus:ring-cyan-500',
      link: 'text-cyan-600 hover:text-cyan-700 underline focus:ring-cyan-500'
    }
  }
  classes.push(typeVariantClasses[props.type][props.variant])

  // 其他样式
  if (props.block) classes.push('w-full')
  if (props.round) classes.push('rounded-full')
  else classes.push('rounded-md')

  return classes.join(' ')
})

const handleClick = (event: MouseEvent) => {
  if (!props.disabled && !props.loading) {
    emit('click', event)
  }
}
</script>

3.2 业务组件设计

<!-- components/business/UserTable.vue -->
<template>
  <div class="user-table">
    <!-- 表格工具栏 -->
    <div class="flex justify-between items-center mb-4">
      <div class="flex items-center space-x-4">
        <BaseInput
          v-model="searchKeyword"
          placeholder="搜索用户..."
          class="w-64"
        >
          <template #prefix>
            <BaseIcon name="search" />
          </template>
        </BaseInput>
        
        <BaseSelect
          v-model="statusFilter"
          placeholder="状态筛选"
          :options="statusOptions"
          clearable
        />
      </div>
      
      <BaseButton
        type="primary"
        icon="plus"
        @click="handleCreateUser"
      >
        新增用户
      </BaseButton>
    </div>

    <!-- 数据表格 -->
    <BaseTable
      :columns="columns"
      :data="users"
      :loading="loading"
      :pagination="pagination"
      @sort-change="handleSortChange"
      @page-change="handlePageChange"
    >
      <template #avatar="{ row }">
        <BaseAvatar
          :src="row.avatar"
          :name="row.name"
          size="small"
        />
      </template>

      <template #status="{ row }">
        <BaseBadge
          :type="getStatusType(row.status)"
          :text="getStatusText(row.status)"
        />
      </template>

      <template #actions="{ row }">
        <div class="flex items-center space-x-2">
          <BaseButton
            size="small"
            variant="ghost"
            icon="edit"
            @click="handleEditUser(row)"
          >
            编辑
          </BaseButton>
          
          <BaseButton
            size="small"
            variant="ghost"
            type="danger"
            icon="delete"
            @click="handleDeleteUser(row)"
          >
            删除
          </BaseButton>
        </div>
      </template>
    </BaseTable>

    <!-- 用户编辑弹窗 -->
    <UserEditModal
      v-model:visible="editModalVisible"
      :user="currentUser"
      @success="handleEditSuccess"
    />
  </div>
</template>

<script setup lang="ts">
import { ref, computed, watch } from 'vue'
import { useUserManagement } from '@/composables/useUserManagement'
import type { User, UserStatus } from '@/types/user'
import type { TableColumn, TablePagination, SortChangeEvent } from '@/types/table'

// 组件属性
export interface UserTableProps {
  height?: string | number
  showPagination?: boolean
}

// 组件事件
export interface UserTableEmits {
  userSelect: [user: User]
  userCreate: [user: User]
  userUpdate: [user: User]
  userDelete: [userId: string]
}

const props = withDefaults(defineProps<UserTableProps>(), {
  showPagination: true
})

const emit = defineEmits<UserTableEmits>()

// 使用用户管理组合函数
const {
  loading,
  users,
  total,
  currentPage,
  totalPages,
  fetchUsers,
  createUser,
  updateUser,
  deleteUser
} = useUserManagement()

// 本地状态
const searchKeyword = ref('')
const statusFilter = ref<UserStatus>()
const editModalVisible = ref(false)
const currentUser = ref<User>()

// 状态选项
const statusOptions = [
  { label: '活跃', value: 'active' },
  { label: '禁用', value: 'disabled' },
  { label: '待激活', value: 'pending' }
]

// 表格列配置
const columns: TableColumn[] = [
  {
    key: 'avatar',
    title: '头像',
    width: 80,
    align: 'center'
  },
  {
    key: 'name',
    title: '姓名',
    sortable: true,
    minWidth: 120
  },
  {
    key: 'email',
    title: '邮箱',
    sortable: true,
    minWidth: 200
  },
  {
    key: 'role',
    title: '角色',
    width: 100
  },
  {
    key: 'status',
    title: '状态',
    width: 100,
    align: 'center'
  },
  {
    key: 'createdAt',
    title: '创建时间',
    sortable: true,
    width: 180,
    formatter: (value: string) => new Date(value).toLocaleString()
  },
  {
    key: 'actions',
    title: '操作',
    width: 150,
    align: 'center'
  }
]

// 分页配置
const pagination = computed<TablePagination>(() => ({
  current: currentPage.value,
  total: total.value,
  pageSize: 20,
  showSizeChanger: true,
  showQuickJumper: true,
  showTotal: true
}))

// 获取状态类型
const getStatusType = (status: UserStatus) => {
  const typeMap = {
    active: 'success',
    disabled: 'danger',
    pending: 'warning'
  } as const
  return typeMap[status] || 'info'
}

// 获取状态文本
const getStatusText = (status: UserStatus) => {
  const textMap = {
    active: '活跃',
    disabled: '禁用',
    pending: '待激活'
  }
  return textMap[status] || status
}

// 事件处理
const handleCreateUser = () => {
  currentUser.value = undefined
  editModalVisible.value = true
}

const handleEditUser = (user: User) => {
  currentUser.value = user
  editModalVisible.value = true
  emit('userSelect', user)
}

const handleDeleteUser = async (user: User) => {
  try {
    await deleteUser(user.id)
    emit('userDelete', user.id)
  } catch (error) {
    console.error('删除用户失败:', error)
  }
}

const handleEditSuccess = (user: User) => {
  editModalVisible.value = false
  if (currentUser.value) {
    emit('userUpdate', user)
  } else {
    emit('userCreate', user)
  }
}

const handleSortChange = (event: SortChangeEvent) => {
  // 处理排序变化
  console.log('Sort change:', event)
}

const handlePageChange = (page: number) => {
  fetchUsers(page)
}

// 监听搜索和筛选条件
watch([searchKeyword, statusFilter], () => {
  // 重新获取数据
  fetchUsers(1)
})
</script>

4. 状态管理与数据流

4.1 Pinia Store设计

// stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import type { User, UserProfile, LoginCredentials } from '@/types/user'
import { userApi } from '@/api/modules/user'
import { useLocalStorage } from '@/hooks/useLocalStorage'

export const useUserStore = defineStore('user', () => {
  // 状态
  const currentUser = ref<User | null>(null)
  const userProfile = ref<UserProfile | null>(null)
  const permissions = ref<string[]>([])
  const [token, setToken, removeToken] = useLocalStorage('auth_token', '')

  // 计算属性
  const isLoggedIn = computed(() => !!currentUser.value && !!token.value)
  const userRoles = computed(() => currentUser.value?.roles || [])
  const hasPermission = computed(() => (permission: string) => 
    permissions.value.includes(permission)
  )

  // 登录
  const login = async (credentials: LoginCredentials) => {
    try {
      const response = await userApi.login(credentials)
      
      currentUser.value = response.user
      setToken(response.token)
      permissions.value = response.permissions
      
      // 获取用户详细信息
      await fetchUserProfile()
      
      return response
    } catch (error) {
      console.error('登录失败:', error)
      throw error
    }
  }

  // 登出
  const logout = async () => {
    try {
      if (token.value) {
        await userApi.logout()
      }
    } catch (error) {
      console.error('登出失败:', error)
    } finally {
      currentUser.value = null
      userProfile.value = null
      permissions.value = []
      removeToken()
    }
  }

  // 获取用户信息
  const fetchUserProfile = async () => {
    try {
      if (!currentUser.value) return
      
      const profile = await userApi.getUserProfile(currentUser.value.id)
      userProfile.value = profile
      
      return profile
    } catch (error) {
      console.error('获取用户信息失败:', error)
      throw error
    }
  }

  // 更新用户信息
  const updateProfile = async (profileData: Partial<UserProfile>) => {
    try {
      if (!currentUser.value) throw new Error('用户未登录')
      
      const updatedProfile = await userApi.updateUserProfile(
        currentUser.value.id,
        profileData
      )
      
      userProfile.value = updatedProfile
      
      return updatedProfile
    } catch (error) {
      console.error('更新用户信息失败:', error)
      throw error
    }
  }

  // 检查权限
  const checkPermission = (permission: string): boolean => {
    return permissions.value.includes(permission)
  }

  // 检查角色
  const hasRole = (role: string): boolean => {
    return userRoles.value.includes(role)
  }

  // 初始化用户状态
  const initializeAuth = async () => {
    if (!token.value) return false
    
    try {
      const userInfo = await userApi.getCurrentUser()
      currentUser.value = userInfo.user
      permissions.value = userInfo.permissions
      
      await fetchUserProfile()
      
      return true
    } catch (error) {
      console.error('初始化认证状态失败:', error)
      // 清除无效token
      removeToken()
      return false
    }
  }

  return {
    // 状态
    currentUser: readonly(currentUser),
    userProfile: readonly(userProfile),
    permissions: readonly(permissions),
    token: readonly(token),
    
    // 计算属性
    isLoggedIn,
    userRoles,
    hasPermission,
    
    // 方法
    login,
    logout,
    fetchUserProfile,
    updateProfile,
    checkPermission,
    hasRole,
    initializeAuth
  }
})

// stores/app.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'
import type { Theme, Language, AppConfig } from '@/types/app'

export const useAppStore = defineStore('app', () => {
  // 应用配置
  const theme = ref<Theme>('light')
  const language = ref<Language>('zh-CN')
  const sidebarCollapsed = ref(false)
  const loading = ref(false)
  
  // 应用配置
  const config = ref<AppConfig>({
    title: 'Vue 3 Admin',
    version: '1.0.0',
    apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
    enableMock: import.meta.env.VITE_ENABLE_MOCK === 'true'
  })

  // 切换主题
  const toggleTheme = () => {
    theme.value = theme.value === 'light' ? 'dark' : 'light'
    document.documentElement.setAttribute('data-theme', theme.value)
  }

  // 设置语言
  const setLanguage = (lang: Language) => {
    language.value = lang
  }

  // 切换侧边栏
  const toggleSidebar = () => {
    sidebarCollapsed.value = !sidebarCollapsed.value
  }

  // 设置加载状态
  const setLoading = (isLoading: boolean) => {
    loading.value = isLoading
  }

  // 初始化应用
  const initializeApp = () => {
    // 从localStorage恢复设置
    const savedTheme = localStorage.getItem('theme') as Theme
    if (savedTheme) {
      theme.value = savedTheme
      document.documentElement.setAttribute('data-theme', savedTheme)
    }

    const savedLanguage = localStorage.getItem('language') as Language
    if (savedLanguage) {
      language.value = savedLanguage
    }

    const savedSidebarState = localStorage.getItem('sidebarCollapsed')
    if (savedSidebarState) {
      sidebarCollapsed.value = JSON.parse(savedSidebarState)
    }
  }

  // 监听状态变化并持久化
  watch(theme, (newTheme) => {
    localStorage.setItem('theme', newTheme)
  })

  watch(language, (newLanguage) => {
    localStorage.setItem('language', newLanguage)
  })

  watch(sidebarCollapsed, (newState) => {
    localStorage.setItem('sidebarCollapsed', JSON.stringify(newState))
  })

  return {
    // 状态
    theme: readonly(theme),
    language: readonly(language),
    sidebarCollapsed: readonly(sidebarCollapsed),
    loading: readonly(loading),
    config: readonly(config),
    
    // 方法
    toggleTheme,
    setLanguage,
    toggleSidebar,
    setLoading,
    initializeApp
  }
})

5. 路由设计与权限控制

5.1 路由配置

图1：路由权限控制流程图

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import type { RouteRecordRaw } from 'vue-router'
import { useUserStore } from '@/stores/user'
import { useAppStore } from '@/stores/app'

// 路由类型定义
export interface AppRouteRecordRaw extends Omit<RouteRecordRaw, 'children'> {
  children?: AppRouteRecordRaw[]
  meta?: {
    title?: string
    icon?: string
    requiresAuth?: boolean
    permissions?: string[]
    roles?: string[]
    hidden?: boolean
    keepAlive?: boolean
    breadcrumb?: boolean
  }
}

// 基础路由（无需权限）
const basicRoutes: AppRouteRecordRaw[] = [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/views/auth/LoginView.vue'),
    meta: {
      title: '登录',
      hidden: true
    }
  },
  {
    path: '/404',
    name: 'NotFound',
    component: () => import('@/views/error/404View.vue'),
    meta: {
      title: '页面不存在',
      hidden: true
    }
  },
  {
    path: '/403',
    name: 'Forbidden',
    component: () => import('@/views/error/403View.vue'),
    meta: {
      title: '无权限访问',
      hidden: true
    }
  }
]

// 主要路由（需要权限）
const mainRoutes: AppRouteRecordRaw[] = [
  {
    path: '/',
    name: 'Layout',
    component: () => import('@/layouts/MainLayout.vue'),
    redirect: '/dashboard',
    children: [
      {
        path: '/dashboard',
        name: 'Dashboard',
        component: () => import('@/views/dashboard/DashboardView.vue'),
        meta: {
          title: '仪表盘',
          icon: 'dashboard',
          requiresAuth: true
        }
      },
      {
        path: '/users',
        name: 'UserManagement',
        component: () => import('@/views/user/UserManagement.vue'),
        meta: {
          title: '用户管理',
          icon: 'users',
          requiresAuth: true,
          permissions: ['user:read']
        }
      },
      {
        path: '/users/create',
        name: 'UserCreate',
        component: () => import('@/views/user/UserCreate.vue'),
        meta: {
          title: '创建用户',
          requiresAuth: true,
          permissions: ['user:create'],
          hidden: true,
          breadcrumb: true
        }
      },
      {
        path: '/users/:id/edit',
        name: 'UserEdit',
        component: () => import('@/views/user/UserEdit.vue'),
        meta: {
          title: '编辑用户',
          requiresAuth: true,
          permissions: ['user:update'],
          hidden: true,
          breadcrumb: true
        }
      },
      {
        path: '/settings',
        name: 'Settings',
        component: () => import('@/views/settings/SettingsView.vue'),
        meta: {
          title: '系统设置',
          icon: 'settings',
          requiresAuth: true,
          roles: ['admin']
        }
      }
    ]
  }
]

// 创建路由实例
const router = createRouter({
  history: createWebHistory(),
  routes: [...basicRoutes, ...mainRoutes],
  scrollBehavior(to, from, savedPosition) {
    if (savedPosition) {
      return savedPosition
    } else {
      return { top: 0 }
    }
  }
})

// 路由守卫
router.beforeEach(async (to, from, next) => {
  const userStore = useUserStore()
  const appStore = useAppStore()
  
  // 显示加载状态
  appStore.setLoading(true)

  try {
    // 如果访问登录页且已登录，重定向到首页
    if (to.name === 'Login' && userStore.isLoggedIn) {
      next({ name: 'Dashboard' })
      return
    }

    // 如果路由需要认证
    if (to.meta?.requiresAuth) {
      // 检查是否已登录
      if (!userStore.isLoggedIn) {
        next({
          name: 'Login',
          query: { redirect: to.fullPath }
        })
        return
      }

      // 检查权限
      if (to.meta.permissions?.length) {
        const hasPermission = to.meta.permissions.some(permission =>
          userStore.checkPermission(permission)
        )
        if (!hasPermission) {
          next({ name: 'Forbidden' })
          return
        }
      }

      // 检查角色
      if (to.meta.roles?.length) {
        const hasRole = to.meta.roles.some(role =>
          userStore.hasRole(role)
        )
        if (!hasRole) {
          next({ name: 'Forbidden' })
          return
        }
      }
    }

    next()
  } catch (error) {
    console.error('路由守卫错误:', error)
    next({ name: 'Login' })
  }
})

router.afterEach((to) => {
  const appStore = useAppStore()
  
  // 隐藏加载状态
  appStore.setLoading(false)
  
  // 设置页面标题
  if (to.meta?.title) {
    document.title = `${to.meta.title} - ${appStore.config.title}`
  }
})

export default router

5.2 动态路由生成

// utils/routeHelper.ts
import type { RouteRecordRaw } from 'vue-router'
import type { AppRouteRecordRaw } from '@/router'

// 动态导入组件
const modules = import.meta.glob('@/views/**/*.vue')

export function generateRoutes(menuData: any[]): AppRouteRecordRaw[] {
  return menuData.map(item => {
    const route: AppRouteRecordRaw = {
      path: item.path,
      name: item.name,
      component: loadComponent(item.component),
      meta: {
        title: item.title,
        icon: item.icon,
        requiresAuth: item.requiresAuth,
        permissions: item.permissions,
        roles: item.roles,
        hidden: item.hidden,
        keepAlive: item.keepAlive
      }
    }

    if (item.children?.length) {
      route.children = generateRoutes(item.children)
    }

    return route
  })
}

function loadComponent(componentPath: string) {
  const path = `/src/views/${componentPath}.vue`
  return modules[path] || (() => import('@/views/error/404View.vue'))
}

// 路由权限检查工具
export function hasRoutePermission(
  route: AppRouteRecordRaw,
  userPermissions: string[],
  userRoles: string[]
): boolean {
  // 检查权限
  if (route.meta?.permissions?.length) {
    const hasPermission = route.meta.permissions.some(permission =>
      userPermissions.includes(permission)
    )
    if (!hasPermission) return false
  }

  // 检查角色
  if (route.meta?.roles?.length) {
    const hasRole = route.meta.roles.some(role =>
      userRoles.includes(role)
    )
    if (!hasRole) return false
  }

  return true
}

// 过滤路由菜单
export function filterRouteMenu(
  routes: AppRouteRecordRaw[],
  userPermissions: string[],
  userRoles: string[]
): AppRouteRecordRaw[] {
  return routes.filter(route => {
    // 隐藏的路由不显示在菜单中
    if (route.meta?.hidden) return false

    // 检查权限
    if (!hasRoutePermission(route, userPermissions, userRoles)) {
      return false
    }

    // 递归过滤子路由
    if (route.children?.length) {
      route.children = filterRouteMenu(route.children, userPermissions, userRoles)
    }

    return true
  })
}

6. API接口与类型定义

6.1 API请求封装

// api/request.ts
import axios from 'axios'
import type { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios'
import { useUserStore } from '@/stores/user'
import { useAppStore } from '@/stores/app'
import router from '@/router'

// 请求配置接口
export interface RequestConfig extends AxiosRequestConfig {
  skipAuth?: boolean
  skipErrorHandler?: boolean
  showLoading?: boolean
}

// 响应数据接口
export interface ApiResponse<T = any> {
  code: number
  message: string
  data: T
  timestamp: number
}

// 分页响应接口
export interface PaginatedResponse<T = any> {
  data: T[]
  total: number
  page: number
  pageSize: number
  totalPages: number
}

class ApiClient {
  private instance: AxiosInstance

  constructor() {
    this.instance = axios.create({
      baseURL: import.meta.env.VITE_API_BASE_URL,
      timeout: 10000,
      headers: {
        'Content-Type': 'application/json'
      }
    })

    this.setupInterceptors()
  }

  private setupInterceptors() {
    // 请求拦截器
    this.instance.interceptors.request.use(
      (config: RequestConfig) => {
        const userStore = useUserStore()
        const appStore = useAppStore()

        // 添加认证token
        if (!config.skipAuth && userStore.token) {
          config.headers = config.headers || {}
          config.headers.Authorization = `Bearer ${userStore.token}`
        }

        // 显示加载状态
        if (config.showLoading) {
          appStore.setLoading(true)
        }

        // 添加请求ID用于追踪
        config.headers = config.headers || {}
        config.headers['X-Request-ID'] = this.generateRequestId()

        return config
      },
      (error) => {
        return Promise.reject(error)
      }
    )

    // 响应拦截器
    this.instance.interceptors.response.use(
      (response: AxiosResponse<ApiResponse>) => {
        const appStore = useAppStore()
        appStore.setLoading(false)

        const { code, message, data } = response.data

        // 处理业务错误
        if (code !== 200) {
          const error = new Error(message)
          error.name = 'BusinessError'
          return Promise.reject(error)
        }

        return data
      },
      (error) => {
        const appStore = useAppStore()
        const userStore = useUserStore()
        
        appStore.setLoading(false)

        // 处理HTTP错误
        if (error.response) {
          const { status, data } = error.response

          switch (status) {
            case 401:
              // 未授权，清除用户信息并跳转登录
              userStore.logout()
              router.push('/login')
              break
            case 403:
              // 无权限
              router.push('/403')
              break
            case 404:
              // 资源不存在
              console.error('API接口不存在:', error.config?.url)
              break
            case 500:
              // 服务器错误
              console.error('服务器内部错误:', data?.message)
              break
            default:
              console.error('请求错误:', data?.message || error.message)
          }

          return Promise.reject(new Error(data?.message || '请求失败'))
        }

        // 网络错误
        if (error.code === 'ECONNABORTED') {
          return Promise.reject(new Error('请求超时'))
        }

        return Promise.reject(new Error('网络错误'))
      }
    )
  }

  private generateRequestId(): string {
    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
  }

  // GET请求
  get<T = any>(url: string, config?: RequestConfig): Promise<T> {
    return this.instance.get(url, config)
  }

  // POST请求
  post<T = any>(url: string, data?: any, config?: RequestConfig): Promise<T> {
    return this.instance.post(url, data, config)
  }

  // PUT请求
  put<T = any>(url: string, data?: any, config?: RequestConfig): Promise<T> {
    return this.instance.put(url, data, config)
  }

  // DELETE请求
  delete<T = any>(url: string, config?: RequestConfig): Promise<T> {
    return this.instance.delete(url, config)
  }

  // PATCH请求
  patch<T = any>(url: string, data?: any, config?: RequestConfig): Promise<T> {
    return this.instance.patch(url, data, config)
  }

  // 上传文件
  upload<T = any>(
    url: string,
    file: File,
    onProgress?: (progress: number) => void,
    config?: RequestConfig
  ): Promise<T> {
    const formData = new FormData()
    formData.append('file', file)

    return this.instance.post(url, formData, {
      ...config,
      headers: {
        'Content-Type': 'multipart/form-data',
        ...config?.headers
      },
      onUploadProgress: (progressEvent) => {
        if (onProgress && progressEvent.total) {
          const progress = Math.round(
            (progressEvent.loaded * 100) / progressEvent.total
          )
          onProgress(progress)
        }
      }
    })
  }
}

export const apiClient = new ApiClient()
export default apiClient

6.2 类型定义

// types/user.ts
export interface User {
  id: string
  username: string
  email: string
  name: string
  avatar?: string
  phone?: string
  status: UserStatus
  roles: string[]
  createdAt: string
  updatedAt: string
}

export interface UserProfile extends User {
  bio?: string
  location?: string
  website?: string
  socialLinks?: {
    github?: string
    twitter?: string
    linkedin?: string
  }
  preferences: {
    theme: 'light' | 'dark'
    language: string
    timezone: string
    notifications: {
      email: boolean
      push: boolean
      sms: boolean
    }
  }
}

export type UserStatus = 'active' | 'disabled' | 'pending'

export interface UserFilter {
  keyword?: string
  status?: UserStatus
  role?: string
  dateRange?: [string, string]
}

export interface LoginCredentials {
  username: string
  password: string
  remember?: boolean
}

export interface LoginResponse {
  user: User
  token: string
  refreshToken: string
  permissions: string[]
  expiresIn: number
}

export interface UserListResponse extends PaginatedResponse<User> {}

// types/table.ts
export interface TableColumn {
  key: string
  title: string
  width?: number | string
  minWidth?: number | string
  align?: 'left' | 'center' | 'right'
  sortable?: boolean
  filterable?: boolean
  fixed?: 'left' | 'right'
  formatter?: (value: any, row: any) => string
  render?: (value: any, row: any) => any
}

export interface TablePagination {
  current: number
  total: number
  pageSize: number
  showSizeChanger?: boolean
  showQuickJumper?: boolean
  showTotal?: boolean
  pageSizeOptions?: number[]
}

export interface SortChangeEvent {
  column: TableColumn
  key: string
  order: 'asc' | 'desc' | null
}

// types/app.ts
export type Theme = 'light' | 'dark'
export type Language = 'zh-CN' | 'en-US'

export interface AppConfig {
  title: string
  version: string
  apiBaseUrl: string
  enableMock: boolean
}

export interface MenuItem {
  id: string
  title: string
  path: string
  icon?: string
  children?: MenuItem[]
  permissions?: string[]
  roles?: string[]
  hidden?: boolean
}

export interface BreadcrumbItem {
  title: string
  path?: string
}

7. 性能优化策略

7.1 组件懒加载与代码分割

// router/lazyLoad.ts
import type { Component } from 'vue'
import { defineAsyncComponent } from 'vue'
import LoadingComponent from '@/components/base/LoadingComponent.vue'
import ErrorComponent from '@/components/base/ErrorComponent.vue'

// 懒加载组件工厂函数
export function createAsyncComponent(
  loader: () => Promise<Component>,
  options?: {
    delay?: number
    timeout?: number
    suspensible?: boolean
  }
) {
  const { delay = 200, timeout = 30000, suspensible = false } = options || {}

  return defineAsyncComponent({
    loader,
    loadingComponent: LoadingComponent,
    errorComponent: ErrorComponent,
    delay,
    timeout,
    suspensible
  })
}

// 路由懒加载
export const lazyLoad = (componentPath: string) => {
  return createAsyncComponent(
    () => import(`@/views/${componentPath}.vue`),
    {
      delay: 200,
      timeout: 30000
    }
  )
}

// 组件懒加载示例
export const AsyncUserTable = createAsyncComponent(
  () => import('@/components/business/UserTable.vue'),
  { delay: 100 }
)

7.2 虚拟滚动优化

<!-- components/base/VirtualList.vue -->
<template>
  <div
    ref="containerRef"
    class="virtual-list"
    :style="{ height: `${height}px` }"
    @scroll="handleScroll"
  >
    <div
      class="virtual-list-phantom"
      :style="{ height: `${totalHeight}px` }"
    />
    
    <div
      class="virtual-list-content"
      :style="{ transform: `translateY(${offsetY}px)` }"
    >
      <div
        v-for="item in visibleItems"
        :key="getItemKey(item.data)"
        class="virtual-list-item"
        :style="{ height: `${itemHeight}px` }"
      >
        <slot :item="item.data" :index="item.index" />
      </div>
    </div>
  </div>
</template>

<script setup lang="ts" generic="T">
import { ref, computed, onMounted, onUnmounted } from 'vue'

export interface VirtualListProps<T> {
  items: T[]
  itemHeight: number
  height: number
  buffer?: number
  keyField?: keyof T
}

export interface VirtualListEmits {
  scroll: [event: Event]
  reachBottom: []
}

const props = withDefaults(defineProps<VirtualListProps<T>>(), {
  buffer: 5,
  keyField: 'id' as keyof T
})

const emit = defineEmits<VirtualListEmits>()

const containerRef = ref<HTMLElement>()
const scrollTop = ref(0)

// 计算属性
const totalHeight = computed(() => props.items.length * props.itemHeight)

const visibleCount = computed(() => Math.ceil(props.height / props.itemHeight))

const startIndex = computed(() => {
  const index = Math.floor(scrollTop.value / props.itemHeight)
  return Math.max(0, index - props.buffer)
})

const endIndex = computed(() => {
  const index = startIndex.value + visibleCount.value + props.buffer * 2
  return Math.min(props.items.length, index)
})

const visibleItems = computed(() => {
  const items = []
  for (let i = startIndex.value; i < endIndex.value; i++) {
    items.push({
      data: props.items[i],
      index: i
    })
  }
  return items
})

const offsetY = computed(() => startIndex.value * props.itemHeight)

// 获取项目key
const getItemKey = (item: T): string | number => {
  if (typeof props.keyField === 'string' && item[props.keyField]) {
    return item[props.keyField] as string | number
  }
  return JSON.stringify(item)
}

// 滚动处理
const handleScroll = (event: Event) => {
  const target = event.target as HTMLElement
  scrollTop.value = target.scrollTop
  
  emit('scroll', event)
  
  // 检查是否到达底部
  const { scrollTop: top, scrollHeight, clientHeight } = target
  if (top + clientHeight >= scrollHeight - 10) {
    emit('reachBottom')
  }
}

// 滚动到指定位置
const scrollToIndex = (index: number) => {
  if (containerRef.value) {
    const targetScrollTop = index * props.itemHeight
    containerRef.value.scrollTop = targetScrollTop
  }
}

// 滚动到顶部
const scrollToTop = () => {
  scrollToIndex(0)
}

// 滚动到底部
const scrollToBottom = () => {
  scrollToIndex(props.items.length - 1)
}

defineExpose({
  scrollToIndex,
  scrollToTop,
  scrollToBottom
})
</script>

<style scoped>
.virtual-list {
  position: relative;
  overflow-y: auto;
}

.virtual-list-phantom {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  z-index: -1;
}

.virtual-list-content {
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
}

.virtual-list-item {
  box-sizing: border-box;
}
</style>

8. 测试策略与质量保证

8.1 单元测试

// tests/unit/composables/useUserManagement.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { useUserManagement } from '@/composables/useUserManagement'
import { userApi } from '@/api/modules/user'

// Mock API
vi.mock('@/api/modules/user', () => ({
  userApi: {
    getUsers: vi.fn(),
    createUser: vi.fn(),
    updateUser: vi.fn(),
    deleteUser: vi.fn()
  }
}))

describe('useUserManagement', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('should initialize with default values', () => {
    const { loading, users, total, currentPage } = useUserManagement({
      autoLoad: false
    })

    expect(loading.value).toBe(false)
    expect(users.value).toEqual([])
    expect(total.value).toBe(0)
    expect(currentPage.value).toBe(1)
  })

  it('should fetch users successfully', async () => {
    const mockUsers = [
      { id: '1', name: 'User 1', email: 'user1@example.com' },
      { id: '2', name: 'User 2', email: 'user2@example.com' }
    ]

    const mockResponse = {
      data: mockUsers,
      total: 2,
      page: 1,
      pageSize: 20
    }

    vi.mocked(userApi.getUsers).mockResolvedValue(mockResponse)

    const { fetchUsers, users, total, loading } = useUserManagement({
      autoLoad: false
    })

    expect(loading.value).toBe(false)

    const result = await fetchUsers()

    expect(userApi.getUsers).toHaveBeenCalledWith({
      page: 1,
      pageSize: 20,
      keyword: '',
      status: undefined,
      role: undefined,
      dateRange: undefined
    })

    expect(users.value).toEqual(mockUsers)
    expect(total.value).toBe(2)
    expect(result).toEqual(mockResponse)
  })

  it('should handle create user', async () => {
    const newUser = {
      name: 'New User',
      email: 'newuser@example.com',
      status: 'active' as const
    }

    const createdUser = {
      id: '3',
      ...newUser,
      createdAt: '2023-01-01T00:00:00Z',
      updatedAt: '2023-01-01T00:00:00Z'
    }

    vi.mocked(userApi.createUser).mockResolvedValue(createdUser)

    const { createUser, users, total } = useUserManagement({
      autoLoad: false
    })

    const result = await createUser(newUser)

    expect(userApi.createUser).toHaveBeenCalledWith(newUser)
    expect(users.value).toContain(createdUser)
    expect(total.value).toBe(1)
    expect(result).toEqual(createdUser)
  })

  it('should handle errors gracefully', async () => {
    const errorMessage = 'Network error'
    vi.mocked(userApi.getUsers).mockRejectedValue(new Error(errorMessage))

    const { fetchUsers } = useUserManagement({ autoLoad: false })

    await expect(fetchUsers()).rejects.toThrow(errorMessage)
  })
})

8.2 组件测试

// tests/unit/components/BaseButton.test.ts
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import BaseButton from '@/components/base/BaseButton.vue'

describe('BaseButton', () => {
  it('renders correctly with default props', () => {
    const wrapper = mount(BaseButton, {
      slots: {
        default: 'Click me'
      }
    })

    expect(wrapper.text()).toBe('Click me')
    expect(wrapper.classes()).toContain('bg-blue-600')
    expect(wrapper.attributes('type')).toBe('button')
  })

  it('applies correct classes for different types', () => {
    const wrapper = mount(BaseButton, {
      props: {
        type: 'danger',
        variant: 'outline'
      }
    })

    expect(wrapper.classes()).toContain('border-red-600')
    expect(wrapper.classes()).toContain('text-red-600')
  })

  it('shows loading state correctly', () => {
    const wrapper = mount(BaseButton, {
      props: {
        loading: true,
        icon: 'plus'
      },
      slots: {
        default: 'Loading'
      }
    })

    expect(wrapper.find('[name="loading"]').exists()).toBe(true)
    expect(wrapper.find('[name="plus"]').exists()).toBe(false)
    expect(wrapper.attributes('disabled')).toBeDefined()
  })

  it('emits click event when clicked', async () => {
    const wrapper = mount(BaseButton)

    await wrapper.trigger('click')

    expect(wrapper.emitted('click')).toHaveLength(1)
  })

  it('does not emit click when disabled', async () => {
    const wrapper = mount(BaseButton, {
      props: {
        disabled: true
      }
    })

    await wrapper.trigger('click')

    expect(wrapper.emitted('click')).toBeUndefined()
  })

  it('does not emit click when loading', async () => {
    const wrapper = mount(BaseButton, {
      props: {
        loading: true
      }
    })

    await wrapper.trigger('click')

    expect(wrapper.emitted('click')).toBeUndefined()
  })
})

9. 构建优化与部署

9.1 Vite配置优化

// vite.config.ts
import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'
import { visualizer } from 'rollup-plugin-visualizer'
import { createHtmlPlugin } from 'vite-plugin-html'

export default defineConfig(({ command, mode }) => {
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    plugins: [
      vue(),
      
      // HTML模板插件
      createHtmlPlugin({
        inject: {
          data: {
            title: env.VITE_APP_TITLE || 'Vue 3 App',
            description: env.VITE_APP_DESCRIPTION || 'A Vue 3 application'
          }
        }
      }),
      
      // 打包分析插件
      command === 'build' && visualizer({
        filename: 'dist/stats.html',
        open: true,
        gzipSize: true
      })
    ].filter(Boolean),
    
    resolve: {
      alias: {
        '@': resolve(__dirname, 'src'),
        '@/components': resolve(__dirname, 'src/components'),
        '@/utils': resolve(__dirname, 'src/utils'),
        '@/api': resolve(__dirname, 'src/api'),
        '@/types': resolve(__dirname, 'src/types')
      }
    },
    
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: `@import "@/assets/styles/variables.scss";`
        }
      }
    },
    
    build: {
      target: 'es2015',
      outDir: 'dist',
      assetsDir: 'assets',
      sourcemap: mode === 'development',
      
      // 代码分割
      rollupOptions: {
        output: {
          chunkFileNames: 'assets/js/[name]-[hash].js',
          entryFileNames: 'assets/js/[name]-[hash].js',
          assetFileNames: 'assets/[ext]/[name]-[hash].[ext]',
          
          manualChunks: {
            // 第三方库分割
            vendor: ['vue', 'vue-router', 'pinia'],
            ui: ['element-plus'],
            utils: ['axios', 'dayjs', 'lodash-es']
          }
        }
      },
      
      // 压缩配置
      minify: 'terser',
      terserOptions: {
        compress: {
          drop_console: mode === 'production',
          drop_debugger: mode === 'production'
        }
      },
      
      // 资源内联阈值
      assetsInlineLimit: 4096
    },
    
    server: {
      host: '0.0.0.0',
      port: 3000,
      open: true,
      cors: true,
      
      // 代理配置
      proxy: {
        '/api': {
          target: env.VITE_API_BASE_URL,
          changeOrigin: true,
          rewrite: (path) => path.replace(/^\/api/, '')
        }
      }
    },
    
    preview: {
      port: 4173,
      host: '0.0.0.0'
    }
  }
})

9.2 性能监控

图2：前端性能指标趋势图

“在现代前端开发中，性能不仅仅是技术指标，更是用户体验的核心要素。每一毫秒的优化都可能带来用户满意度的显著提升。” —— 前端性能优化原则

总结

Vue 3的Composition API为我们提供了更加灵活和强大的逻辑组织方式，相比传统的Options API，它在类型推导、代码复用、逻辑组合等方面都有显著优势。结合TypeScript的静态类型检查能力，我们能够构建出更加稳定、可维护的大型前端应用。

在项目架构设计方面，合理的目录结构、模块化的组件设计、清晰的状态管理方案，都是确保项目长期可维护性的关键因素。通过Pinia的状态管理、Vue Router的路由控制、以及完善的权限系统，我们能够构建出功能完整、安全可靠的企业级前端应用。

组件设计的类型安全是Vue 3 + TypeScript技术栈的重要优势。通过严格的类型定义、Props验证、事件类型约束，我们能够在开发阶段就发现潜在问题，大大减少运行时错误的发生。

API接口的封装和类型定义为前后端协作提供了标准化的规范。通过统一的请求拦截、响应处理、错误管理机制，我们能够构建出稳定可靠的数据交互层。

性能优化是现代前端应用的重要考量因素。通过组件懒加载、虚拟滚动、代码分割等技术手段，我们能够显著提升应用的加载速度和运行性能，为用户提供更好的使用体验。

测试策略的完善实施为代码质量提供了有力保障。通过单元测试、组件测试、集成测试的全面覆盖，我们能够确保代码的稳定性和可靠性，降低线上问题的发生概率。

构建优化和部署策略的合理配置，能够进一步提升应用的性能表现。通过Vite的现代化构建工具、合理的代码分割策略、以及完善的缓存机制，我们能够实现最优的用户体验。

展望未来，随着Web技术的不断发展，Vue 3 + TypeScript技术栈将在更多场景中发挥重要作用。掌握这些核心技术和最佳实践，将为我们在前端技术快速发展的时代保持竞争优势提供强有力的支撑。

■ 我是蒋星熠Jaxonic！如果这篇文章在你的技术成长路上留下了印记
■ 👁 【关注】与我一起探索技术的无限可能，见证每一次突破
■ 👍 【点赞】为优质技术内容点亮明灯，传递知识的力量
■ 🔖 【收藏】将精华内容珍藏，随时回顾技术要点
■ 💬 【评论】分享你的独特见解，让思维碰撞出智慧火花
■ 🗳 【投票】用你的选择为技术社区贡献一份力量
■ 技术路漫漫，让我们携手前行，在代码的世界里摘取属于程序员的那片星辰大海！

参考链接

1. Vue 3官方文档
2. TypeScript官方文档
3. Vite构建工具文档
4. Pinia状态管理库
5. Vue Router路由管理