Vue 3 + Vite 项目实战：从 0 搭建现代化前端工程

> 标签： vue vite frontend 工程化 javascript
> 作者： @vue_lover
> 发布时间： 2026-06-12

项目概述

本文将带你从零搭建一个基于 Vue 3 + Vite 的现代化前端项目，包含：

Vue 3 Composition API
Vite 构建工具
TypeScript 支持
路由管理（Vue Router）
状态管理（Pinia）
UI 组件库（Element Plus）
代码规范（ESLint + Prettier）

环境准备

# 检查 Node.js 版本（建议 18+）
node -v

# 使用 pnpm（推荐）
npm install -g pnpm

第一步：项目初始化

# 使用 Vite 创建项目
pnpm create vite@latest my-vue-app --template vue-ts

# 进入项目
cd my-vue-app

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

第二步：安装核心依赖

# 路由
pnpm add vue-router@4

# 状态管理
pnpm add pinia

# UI 组件库
pnpm add element-plus

# 图标
pnpm add @element-plus/icons-vue

# HTTP 请求
pnpm add axios

# 工具库
pnpm add lodash-es dayjs

第三步：项目结构规划

my-vue-app/
├── public/                 # 静态资源
├── src/
│   ├── api/               # API 接口
│   ├── assets/            # 样式、图片
│   ├── components/        # 公共组件
│   ├── composables/       # 组合式函数
│   ├── layouts/           # 布局组件
│   ├── router/            # 路由配置
│   ├── stores/            # Pinia 状态
│   ├── utils/             # 工具函数
│   ├── views/             # 页面组件
│   ├── App.vue            # 根组件
│   └── main.ts            # 入口文件
├── .env                   # 环境变量
├── .env.production        # 生产环境
├── vite.config.ts         # Vite 配置
├── tsconfig.json          # TS 配置
└── package.json

第四步：核心配置

4.1 Vite 配置

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'
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()],
      imports: ['vue', 'vue-router', 'pinia']
    }),
    Components({
      resolvers: [ElementPlusResolver()]
    })
  ],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src')
    }
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
        rewrite: (path) =&gt; path.replace(/^\/api/, '')
      }
    }
  },
  build: {
    outDir: 'dist',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          'element-plus': ['element-plus'],
          'vue-vendor': ['vue', 'vue-router', 'pinia']
        }
      }
    }
  }
})

4.2 路由配置

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

const routes = [
  {
    path: '/',
    component: () =&gt; import('@/layouts/MainLayout.vue'),
    children: [
      {
        path: '',
        name: 'Home',
        component: () =&gt; import('@/views/Home.vue')
      },
      {
        path: 'about',
        name: 'About',
        component: () =&gt; import('@/views/About.vue')
      }
    ]
  },
  {
    path: '/login',
    name: 'Login',
    component: () =&gt; import('@/views/Login.vue'),
    meta: { public: true }
  }
]

const router = createRouter({
  history: createWebHistory(),
  routes
})

// 路由守卫
router.beforeEach((to, from, next) =&gt; {
  const userStore = useUserStore()

  if (!to.meta.public &amp;&amp; !userStore.isLoggedIn) {
    next('/login')
  } else {
    next()
  }
})

export default router

4.3 Pinia 状态管理

// src/stores/user.ts
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useUserStore = defineStore('user', () =&gt; {
  // State
  const token = ref(localStorage.getItem('token') || '')
  const userInfo = ref(null)

  // Getters
  const isLoggedIn = computed(() =&gt; !!token.value)

  // Actions
  const login = async (credentials: { username: string; password: string }) =&gt; {
    // API 调用
    const { data } = await api.post('/auth/login', credentials)
    token.value = data.token
    userInfo.value = data.user
    localStorage.setItem('token', data.token)
  }

  const logout = () =&gt; {
    token.value = ''
    userInfo.value = null
    localStorage.removeItem('token')
  }

  return {
    token,
    userInfo,
    isLoggedIn,
    login,
    logout
  }
})

4.4 组合式函数

// src/composables/useTable.ts
import { ref, computed } from 'vue'

export function useTable&lt;T&gt;(fetchFn: (params: any) =&gt; Promise&lt;{ list: T[]; total: number }&gt;) {
  const loading = ref(false)
  const data = ref&lt;T[]&gt;([])
  const total = ref(0)
  const currentPage = ref(1)
  const pageSize = ref(10)

  const pagination = computed(() =&gt; ({
    currentPage: currentPage.value,
    pageSize: pageSize.value,
    total: total.value
  }))

  const fetchData = async (params = {}) =&gt; {
    loading.value = true
    try {
      const result = await fetchFn({
        page: currentPage.value,
        size: pageSize.value,
        ...params
      })
      data.value = result.list
      total.value = result.total
    } finally {
      loading.value = false
    }
  }

  const handlePageChange = (page: number) =&gt; {
    currentPage.value = page
    fetchData()
  }

  return {
    loading,
    data,
    pagination,
    fetchData,
    handlePageChange
  }
}

第五步：实战示例

5.1 用户列表页面

&lt;!-- src/views/UserList.vue --&gt;
&lt;template&gt;
  &lt;div class="user-list"&gt;
    &lt;el-table :data="data" v-loading="loading"&gt;
      &lt;el-table-column prop="id" label="ID" width="80" /&gt;
      &lt;el-table-column prop="username" label="用户名" /&gt;
      &lt;el-table-column prop="email" label="邮箱" /&gt;
      &lt;el-table-column prop="createdAt" label="创建时间"&gt;
        &lt;template #default="{ row }"&gt;
          {{ formatDate(row.createdAt) }}
        &lt;/template&gt;
      &lt;/el-table-column&gt;
      &lt;el-table-column label="操作" width="150"&gt;
        &lt;template #default="{ row }"&gt;
          &lt;el-button type="primary" size="small" @click="editUser(row)"&gt;
            编辑
          &lt;/el-button&gt;
        &lt;/template&gt;
      &lt;/el-table-column&gt;
    &lt;/el-table&gt;

    &lt;el-pagination
      v-model:current-page="pagination.currentPage"
      v-model:page-size="pagination.pageSize"
      :total="pagination.total"
      @current-change="handlePageChange"
      layout="total, prev, pager, next"
    /&gt;
  &lt;/div&gt;
&lt;/template&gt;

&lt;script setup lang="ts"&gt;
import { useTable } from '@/composables/useTable'
import { formatDate } from '@/utils/date'
import { getUserList } from '@/api/user'

const { loading, data, pagination, fetchData, handlePageChange } = useTable(getUserList)

// 初始加载
fetchData()

const editUser = (user: any) =&gt; {
  // 编辑逻辑
}
&lt;/script&gt;

5.2 封装 Axios

// src/utils/request.ts
import axios from 'axios'
import { useUserStore } from '@/stores/user'
import { ElMessage } from 'element-plus'

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

// 请求拦截器
request.interceptors.request.use((config) =&gt; {
  const userStore = useUserStore()
  if (userStore.token) {
    config.headers.Authorization = `Bearer ${userStore.token}`
  }
  return config
})

// 响应拦截器
request.interceptors.response.use(
  (response) =&gt; response.data,
  (error) =&gt; {
    if (error.response?.status === 401) {
      const userStore = useUserStore()
      userStore.logout()
      window.location.href = '/login'
    } else {
      ElMessage.error(error.response?.data?.message || '请求失败')
    }
    return Promise.reject(error)
  }
)

export default request

第六步：构建与部署

# 开发
pnpm dev

# 构建（测试环境）
pnpm build

# 构建（生产环境）
pnpm build --mode production

# 预览生产构建
pnpm preview

Nginx 配置

server {
    listen 80;
    server_name myapp.example.com;
    root /var/www/my-vue-app/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://backend_server;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}