Vite + Vue3 + TS从零搭建企业级项目脚手架

一、前言：为什么选择这个技术栈？

技术选型背景

• Vite ：相比 Webpack，Vite 的「按需编译」和「ESM 原生支持」让开发环境启动速度提升 10 倍以上，热更新几乎无感。

• Vue3 ：Composition API 提供更灵活的代码组织方式，配合 <script setup> 语法糖，开发体验更接近原生 JS。

• TypeScript：企业级项目必备的类型系统，减少联调期的低级错误，提升代码可维护性。

适用场景

• 需要快速搭建高可维护性、可扩展的前端工程

• 团队协作场景下的代码规范约束

二、基础项目初始化

1. 快速创建 Vite 项目

bash 复制代码

# 创建项目并选择 vue-ts 模板
npm create vite@latest my-project -- --template vue-ts
cd my-project && npm install

2. 目录结构规范

markdown 复制代码

src
├── assets        # 静态资源（图片、字体等）
├── components    # 公共组件（按业务/功能分类）
├── router        # 路由配置（Vue Router 4）
├── store         # 状态管理（Pinia 模块化设计）
├── utils         # 工具函数（axios 封装、日期处理等）
├── views         # 页面组件（路由级组件）
├── types         # 全局类型声明
└── main.ts       # 入口文件

3. 安装核心依赖

bash 复制代码

# 运行时代码
npm install vue-router@4 pinia axios sass

# 开发工具链
npm install -D prettier eslint @typescript-eslint/eslint-plugin husky

三、企业级工程化配置

1. 代码规范：ESLint + Prettier

在 .eslintrc.cjs 中配置：

javascript 复制代码

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:vue/vue3-recommended',
    'prettier'
  ],
  rules: {
    'vue/multi-word-component-names': 'off' // 允许单文件组件名
  }
}

2. TypeScript 深度集成

在 types/env.d.ts 中声明全局类型：

typescript 复制代码

// 定义环境变量类型
interface ImportMetaEnv {
  VITE_API_BASE_URL: string;
}

// 扩展组件实例类型
declare module 'vue' {
  interface ComponentCustomProperties {
    $filters: {
      dateFormat: (value: Date) => string;
    };
  }
}

3. 环境变量管理

bash 复制代码

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

四、核心功能模块搭建

1. 路由系统设计（动态权限控制）

typescript 复制代码

// router/index.ts
const routes: RouteRecordRaw[] = [
  {
    path: '/login',
    name: 'Login',
    component: () => import('@/views/Login.vue'),
    meta: { requiresAuth: false }
  },
  {
    path: '/dashboard',
    name: 'Dashboard',
    component: () => import('@/views/Dashboard.vue'),
    meta: { requiresAuth: true }
  }
];

// 路由守卫实现权限校验
router.beforeEach((to) => {
  const store = useUserStore();
  if (to.meta.requiresAuth && !store.token) return '/login';
});

2. Pinia 状态管理（持久化存储）

typescript 复制代码

// store/user.ts
export const useUserStore = defineStore('user', {
  state: () => ({
    token: localStorage.getItem('token') || '',
    roles: [] as string[]
  }),
  persist: true // 启用持久化插件
});

3. Axios 请求封装（拦截器示例）

typescript 复制代码

// utils/request.ts
const service = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 10000
});

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

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

五、性能优化实践

1. 开发阶段优化

在 vite.config.ts 中配置按需加载：

typescript 复制代码

// 以 Element Plus 为例
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: [
    AutoImport({
      resolvers: [ElementPlusResolver()]
    }),
    Components({
      resolvers: [ElementPlusResolver()]
    })
  ]
});

2. 构建阶段优化

typescript 复制代码

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vue: ['vue', 'vue-router', 'pinia'],
          element: ['element-plus']
        }
      }
    }
  }
});

六、质量保障与部署

1. 单元测试（Vitest 示例）

typescript 复制代码

// tests/hello.spec.ts
import { describe, expect, it } from 'vitest';
import { formatDate } from '@/utils/date';

describe('日期工具函数', () => {
  it('formatDate 应返回正确格式', () => {
    const date = new Date('2023-10-01');
    expect(formatDate(date)).toBe('2023年10月01日');
  });
});

2. Nginx 生产配置

nginx 复制代码

server {
  listen 80;
  gzip on;
  gzip_types text/plain application/javascript text/css;

  location / {
    root /usr/share/nginx/html;
    try_files $uri $uri/ /index.html;
    expires 1d;
  }
}

七、实战案例：用户登录鉴权

vue 复制代码

<!-- views/Login.vue -->
<script setup lang="ts">
const form = reactive({ username: '', password: '' });
const { loading, run } = useRequest(() => login(form));

const handleSubmit = async () => {
  await run();
  router.push('/dashboard');
};
</script>

<template>
  <el-form @submit.prevent="handleSubmit">
    <el-input v-model="form.username" placeholder="账号" />
    <el-input v-model="form.password" type="password" />
    <el-button :loading="loading" type="primary" native-type="submit">登录</el-button>
  </el-form>
</template>

八、总结与扩展

脚手架优势

• 开发效率 ：HMR 更新速度 <200ms，构建时间比 Webpack 减少 40%

• 维护成本：统一的代码风格 + 类型约束，降低新人上手难度

扩展方向

• 微前端：通过 vite-plugin-federation 实现模块独立部署

• 自动化：结合 Plop.js 实现组件/页面模板一键生成

立即动手实践，你的 Star 和反馈是我持续输出的动力！ 🚀