从零搭建企业级项目

从零搭建一个企业级前端项目，核心工作不是写业务代码，而是建立一套让团队能够高效协作、持续交付的基础设施。一个设计合理的项目结构应该让新成员在半小时内跑通项目，让十个人的团队像一个人一样提交代码而不产生冲突，让功能迭代和缺陷修复能够独立并行而不互相阻塞。

技术选型

技术选型的原则是"选主流、选稳定、选团队能 hold 住的"。框架层面，Vue 3 和 React 19 是当前的两个主流选择，两者在组件模型、状态管理和生态完善度上各有优势，具体选哪个取决于团队的技术背景和项目需求。构建工具在 2026 年的新项目中几乎不存在争议——Vite 是默认选项，只有在需要兼容大量 Webpack 存量配置的特殊场景下才考虑 Rspack。

TypeScript 在企业级项目中已经是必选项，不是可选项。它的价值不仅在于类型安全，更在于为团队提供了统一的代码契约——接口定义即文档，类型检查即代码审查的第一道防线。使用 strict: true 开启所有严格检查，不要为了短期方便降低类型精度。

CSS 方案的选择需要权衡开发体验和产物体积。Tailwind CSS 在实用类优先的开发模式下效率极高，适合设计规范明确、组件复用度高的项目；CSS Modules 提供了局部作用域的样式隔离，适合需要精细控制样式优先级的场景。两者不冲突，实际项目中可以混用——Tailwind 处理布局和间距等通用样式，CSS Modules 处理组件特有的复杂样式。

包管理器推荐 pnpm。它的硬链接机制节省磁盘空间和安装时间，严格的 node_modules 结构避免了幽灵依赖（phantom dependencies），workspace 协议对 Monorepo 的原生支持也是其他包管理器不具备的。

项目结构

一个典型的企业级前端项目结构如下：

project/
├── public/                    # 静态资源（不经过构建工具处理）
│   └── favicon.ico
├── src/
│   ├── api/                    # 接口层：封装所有 HTTP 请求
│   │   ├── request.ts          # Axios 实例配置（拦截器、超时、错误处理）
│   │   └── modules/            # 按业务域拆分的接口模块
│   │       └── user.ts
│   ├── assets/                 # 需要构建工具处理的静态资源
│   │   ├── images/
│   │   └── styles/
│   │       └── global.css
│   ├── components/             # 通用组件（跨页面复用）
│   │   ├── Button/
│   │   │   ├── Button.vue
│   │   │   ├── Button.test.ts
│   │   │   └── index.ts        # 统一导出
│   │   └── index.ts            # 所有通用组件的统一导出入口
│   ├── composables/            # 可复用的组合式函数（Vue）或自定义 Hooks（React）
│   │   ├── useAuth.ts
│   │   └── useRequest.ts
│   ├── layouts/                # 页面布局组件
│   │   ├── DefaultLayout.vue
│   │   └── BlankLayout.vue
│   ├── pages/                  # 页面级组件（与路由一一对应）
│   │   ├── home/
│   │   │   ├── index.vue
│   │   │   └── components/     # 页面私有组件（不跨页面复用）
│   │   └── login/
│   │       └── index.vue
│   ├── router/                 # 路由配置
│   │   ├── index.ts
│   │   └── modules/
│   ├── stores/                 # 全局状态管理（Pinia / Zustand）
│   │   ├── user.ts
│   │   └── app.ts
│   ├── types/                  # 全局 TypeScript 类型定义
│   │   ├── api.d.ts
│   │   └── global.d.ts
│   ├── utils/                  # 工具函数
│   │   ├── storage.ts
│   │   └── format.ts
│   ├── App.vue                 # 根组件
│   └── main.ts                 # 入口文件
├── .env                        # 默认环境变量
├── .env.development            # 开发环境变量
├── .env.production             # 生产环境变量
├── .gitignore
├── .prettierrc                 # Prettier 配置
├── eslint.config.js            # ESLint 配置
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 构建配置
├── package.json
└── pnpm-lock.yaml

这个结构的组织原则是按职责分层，而非按技术类型分层。api 层负责所有与后端通信的逻辑，components 存放跨页面复用的通用组件，pages 存放与路由一一对应的页面组件及其私有子组件，composables 存放可复用的有状态逻辑，stores 存放全局状态，utils 存放纯函数工具。每一层都有明确的职责边界，开发者新增功能时能快速判断代码应该放在哪个目录。

接口层设计

接口层是企业级项目中最早需要稳定下来的基础设施。所有 HTTP 请求不应该在业务组件中直接调用 fetch 或 axios，而是通过统一的接口层封装。接口层负责三件事：配置 Axios 实例（基础 URL、超时时间、请求拦截器、响应拦截器）、按业务域拆分接口模块、统一错误处理。

请求拦截器负责在请求发出前注入认证令牌（如 Authorization: Bearer <token>）、设置请求的 trace ID 用于日志追踪。响应拦截器负责统一处理 HTTP 错误码——401 跳转登录页、403 显示无权限提示、500 显示服务器错误提示。业务组件只需要调用接口方法并处理成功回调，不需要关心网络层面的异常处理。

// api/request.ts — Axios 实例配置
import axios from 'axios'
import { useAuthStore } from '@/stores/auth'

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

request.interceptors.request.use((config) => {
  const token = useAuthStore().token
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

request.interceptors.response.use(
  (response) => response.data,
  (error) => {
    if (error.response?.status === 401) {
      useAuthStore().logout()
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

export default request

// api/modules/user.ts — 按业务域拆分的接口
import request from '../request'

export function getUserInfo() {
  return request.get('/user/info')
}

export function updateUserProfile(data: UpdateUserDTO) {
  return request.put('/user/profile', data)
}

路由与权限

路由配置应该与页面组件分离，集中管理在一个或多个路由模块文件中。路由守卫（Navigation Guards）负责权限校验——在每次路由跳转前检查用户是否已登录、是否有权限访问目标页面。未登录时重定向到登录页并记录目标路由，登录成功后自动跳转回原目标页面。

动态路由是后台管理类项目中常见的模式。用户的权限列表从后端接口获取后，前端根据权限列表动态注册对应的路由，而不是在路由配置中硬编码所有页面的权限标识。这种方式让权限的变更只需在后端调整，无需前端发版。

// router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import { useAuthStore } from '@/stores/auth'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/login',
      component: () => import('@/pages/login/index.vue'),
      meta: { requiresAuth: false }
    },
    {
      path: '/',
      component: () => import('@/layouts/DefaultLayout.vue'),
      children: [
        {
          path: '',
          component: () => import('@/pages/home/index.vue'),
          meta: { requiresAuth: true }
        }
      ]
    }
  ]
})

router.beforeEach((to) => {
  const auth = useAuthStore()
  if (to.meta.requiresAuth && !auth.isLoggedIn) {
    return { path: '/login', query: { redirect: to.fullPath } }
  }
})

状态管理

全局状态管理存放的是跨组件、跨页面共享的业务数据——用户信息、应用配置、权限列表等。并非所有状态都需要放入全局 Store，组件内部的私有状态应该用组件自身的响应式变量管理。过度使用全局状态会导致数据流难以追踪，维护成本随项目规模急剧上升。

Store 的拆分粒度按业务域划分，每个 Store 文件对应一个业务域（用户、订单、应用配置等），而不是将所有全局状态塞进一个巨大的 Store 对象。Pinia（Vue）和 Zustand（React）都天然支持这种按模块拆分的模式。

// stores/user.ts — 按业务域拆分的 Store
import { defineStore } from 'pinia'
import { getUserInfo } from '@/api/modules/user'

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null as UserInfo | null,
    token: localStorage.getItem('token') || '',
  }),
  actions: {
    async fetchUserInfo() {
      this.userInfo = await getUserInfo()
    },
    logout() {
      this.userInfo = null
      this.token = ''
      localStorage.removeItem('token')
    }
  }
})

组件设计

通用组件（components/ 目录）和页面私有组件（pages/xxx/components/ 目录）的区分是项目结构中的关键约定。通用组件是跨页面复用的，应该做到 props 定义清晰、事件命名规范、无业务逻辑耦合。页面私有组件只在当前页面内使用，不需要考虑复用性，但也不应该直接写在页面文件中——超过 50 行的模板或超过 100 行的脚本逻辑就应该拆分为独立的子组件。

组件目录内的文件组织遵循"单一导出入口"原则：每个组件一个独立目录，目录名即组件名，目录内包含组件文件、样式文件和测试文件，通过 index.ts 统一导出。外部引用时使用 @/components/Button 而非 @/components/Button/Button.vue，减少路径嵌套层级。

构建配置

Vite 配置文件是企业级项目中需要持续维护的基础设施。初始阶段的配置通常包括：路径别名（@ → src/）、开发服务器代理（解决本地跨域）、环境变量声明类型（env.d.ts）。环境变量和多环境配置的管理方式在工程化搭建中详细展开。

开发服务器代理是最常用的配置项，用于将前端请求中 /api 前缀的请求转发到后端开发服务器，避免在本地开发中配置 CORS 或修改 hosts。

// 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')
    }
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      }
    }
  }
})

TypeScript 的路径别名需要与 Vite 配置同步声明，否则编辑器的类型推断和路径跳转无法正常工作。

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    },
    "strict": true
  }
}

启动流程

从零搭建一个企业级项目，实际的执行顺序是：初始化项目（pnpm create vite）→ 配置 TypeScript 严格模式 → 搭建目录结构 → 配置路径别名 → 封装接口层 → 配置路由和权限守卫 → 搭建状态管理。项目骨架稳定后，再接入代码规范（ESLint + Prettier + husky + lint-staged）和 CI/CD 流水线——这两个体系的搭建方式在工程化搭建中详细介绍。

这个过程中，每一层的搭建都应该以"让下一个功能能顺畅开发"为目标，而非追求配置的完备性。项目结构是演进的，不是一次性设计完成的——随着业务复杂度的增长，按需拆分目录、提取公共组件、引入新的工具，比在项目初期就设计一个"完美"的结构要务实得多。