Vue 3 工程化与项目搭建

本文介绍使用 Vite + Vue 3 + TypeScript 创建生产可用项目的完整流程，包括目录结构、别名配置、环境变量、代理设置和代码规范。

工具	版本	说明
Node.js	20.x / 22+	官方 LTS，推荐 22
pnpm	9.x / 10+	比 npm 更快、更省磁盘
VS Code	最新版	配合 Volar 插件

常用技术栈

技术	说明
Vue 3 + `<script setup>`	组合式 API，官方推荐写法
Vite	极速构建工具，HMR 毫秒级
TypeScript	类型安全，减少运行时错误
Vue Router 4	官方路由，支持懒加载和守卫
Pinia	官方状态管理，取代 Vuex
Axios	HTTP 客户端（已封装拦截器）
Element Plus / Ant Design Vue	Vue 3 UI 组件库
ESLint + Prettier	代码检查 + 格式化

1. 创建项目

官方推荐使用 create-vue 脚手架（基于 Vite）：

npm create vue@latest

交互式引导会询问项目名称和可选功能（TypeScript、Router、Pinia、ESLint、Prettier）。全部选 Yes 即可获得开箱即用的配置。

也可以直接用 Vite 模板（功能更少，适合自定义）：

npm create vite@latest my-project -- --template vue-ts
cd my-project
npm install

2. 项目目录结构

my-project/
├── public/              # 静态资源（不会被 Vite 处理）
├── src/
│   ├── assets/          # 图片、字体等（会被 Vite 处理）
│   ├── components/      # 公共组件
│   ├── composables/     # 可组合函数（useXxx）
│   ├── layout/          # 布局组件（Header/Sidebar/Footer）
│   ├── router/          # 路由配置
│   │   └── index.ts
│   ├── stores/          # Pinia Store
│   ├── utils/           # 工具函数（axios 封装等）
│   ├── views/           # 页面级组件
│   ├── App.vue          # 根组件
│   └── main.ts          # 入口文件
├── .env                 # 通用环境变量
├── .env.development     # 开发环境变量
├── .env.production      # 生产环境变量
├── vite.config.ts       # Vite 配置
├── tsconfig.json        # TypeScript 配置
└── package.json

3. Vite 配置

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'),  // 用 @ 代替 src/
    },
  },
  server: {
    port: 5173,
    proxy: {
      // 开发代理，解决跨域
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
    // 分割大依赖
    rollupOptions: {
      output: {
        manualChunks: {
          'vue-vendor': ['vue', 'vue-router', 'pinia'],
        },
      },
    },
  },
})

4. 环境变量

Vite 使用 .env 文件管理环境变量，只有 VITE_ 前缀的变量才会暴露给客户端代码：

# .env.development
VITE_API_BASE_URL=http://localhost:8000/api
VITE_APP_TITLE=我的应用（开发）

# .env.production
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=我的应用

在代码中使用：

const baseURL = import.meta.env.VITE_API_BASE_URL
const title = import.meta.env.VITE_APP_TITLE

5. Axios 封装

// src/utils/request.ts
import axios from 'axios'
import { useAuthStore } from '@/stores/auth'
import router from '@/router'

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

// 请求拦截器：自动附加 Token
request.interceptors.request.use((config) => {
  const auth = useAuthStore()
  if (auth.token) {
    config.headers.Authorization = `Bearer ${auth.token}`
  }
  return config
})

// 响应拦截器：统一处理错误
request.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      router.push('/login')
    }
    return Promise.reject(error)
  }
)

export default request

6. main.ts 入口

// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'

const app = createApp(App)

app.use(createPinia())
app.use(router)

app.mount('#app')

7. 代码规范

Git 提交规范（Conventional Commits）

类型	说明
`feat`	新功能
`fix`	Bug 修复
`perf`	性能优化
`refactor`	重构（不改变功能）
`docs`	文档与注释
`style`	代码格式（不影响逻辑）
`test`	单元测试
`ci`	CI/CD 配置
`chore`	依赖更新、配置修改等杂项
`revert`	撤销提交

提交示例：

git commit -m "feat: 添加用户登录功能"
git commit -m "fix: 修复移动端导航栏层级问题"
git commit -m "perf: 路由懒加载优化首屏体积"

ESLint + Prettier

使用 npm create vue@latest 创建时选择 ESLint + Prettier 会自动配置。手动安装：

npm install -D eslint @eslint/js typescript-eslint eslint-plugin-vue prettier

关键配置（eslint.config.js）：

import pluginVue from 'eslint-plugin-vue'
import { defineConfig } from 'eslint/config'

export default defineConfig([
  pluginVue.configs['flat/essential'],
  {
    rules: {
      'vue/multi-word-component-names': 'off',  // 单词组件名不报错
    },
  },
])

8. 启动与构建

# 开发服务器
npm run dev

# 类型检查
npm run type-check

# 生产构建
npm run build

# 预览构建产物
npm run preview

最后更新于 2026-06-26

Pinia 状态管理