从零开始构建一个现代化前端项目：实战经验分享

开篇：为什么写这篇文章？

去年我参与了一个新项目的启动工作。当时公司要重构一个内部使用的管理后台，目标是打造一个稳定、可维护、易扩展的系统，并且希望能在半年内支持多种业务线接入。

作为一名有5年前端开发经验的老兵，这是我第一次独立负责整个前端技术选型和架构搭建的工作。说实话，一开始我是有点慌的——虽然平时做功能开发没问题，但真要从0到1搭起一整套工程体系，还是挺考验综合实力的。

今天想通过这篇文章，聊聊我当时是怎么一步步把项目搭起来的，包括遇到的问题、踩过的坑、以及最终落地后的一些思考。希望对正在考虑或者准备启动一个新项目的朋友有些帮助。

---

问题描述：需求不明确，挑战接踵而至

项目背景

我们要做一个统一的中后台管理系统，整合多个子系统的数据与操作入口，主要用户群体是产品经理和运营人员。功能涉及权限控制、数据展示、流程审批等常规中台能力。

看起来是个典型的管理类项目，但实际过程中遇到了不少麻烦：

• 需求边界模糊，初期只有几个粗线条的功能模块
• 团队成员对技术选型意见不统一（React vs Vue）
• 后端服务还未就位，前端需要 mock 数据先行开发
• 产品希望尽早看到 UI 效果，设计稿还没完全产出
• 性能和兼容性有硬性要求：支持 Chrome/Firefox/IE11（你没看错）

这些都是典型的前端项目“开工前的混乱期”问题。如果处理不好，轻则进度拖慢，重则返工改架构。

---

解决方案：用现代框架 + 工程化工具搭建基础结构

技术选型决策

在选型上我们做了几轮讨论。React 和 Vue 是主流选择，各有优势。综合权衡了团队熟悉程度、长期维护成本、生态丰富度之后，我们最终选择了 Vue 3 + Vite + TypeScript 的组合。

为什么不是 React？

主要是因为团队中有几名成员更熟悉 Vue，而且考虑到中后台系统的稳定性优先于社区热度，Vue 更适合这个类型的产品场景。

为什么用 Vite？

Vite 在本地开发体验上真的太好了，尤其搭配 Vue 3 的 script setup 语法糖后，写组件就像吃饭喝水一样自然。

为什么引入 TypeScript？

TypeScript 能显著提升代码的可读性和协作效率，尤其是在多人协作和大型项目中。虽然初期学习成本略高，但从长远来看绝对值得。

核心工具链一览

工具	作用
Vite + Vue 3	快速构建项目核心框架
TypeScript	类型安全与团队协作保障
Eslint + Prettier	代码规范与自动格式化
Pinia	状态管理
Vue Router 4	页面路由
Axios	接口封装
Mock.js	接口模拟
Sass + PostCSS	样式预处理器与 CSS 兼容性优化
Storybook	组件文档与隔离开发

此外，为了满足 IE11 支持的需求，我们还配置了 Babel + Polyfill 的机制。

---

代码实践：关键代码示例与配置说明

1. 初始化项目

使用 create-vue 搭建初始化模板：

npm create vue@latest
# 一路回车，记得选中 TypeScript、Vitest、Prettier 等选项

生成后的目录结构很清晰，可以快速进入开发阶段。

2. 状态管理 —— Pinia 替代 Vuex

Pinia 更加简洁直观，推荐直接上手。

创建一个用户模块：

// src/stores/userStore.ts
import { defineStore } from 'pinia'

export const useUserStore = defineStore('user', {
  state: () => ({
    username: '',
    role: 'guest'
  }),
  actions: {
    login(name: string) {
      this.username = name
      this.role = 'admin'
    }
  }
})

然后在 main.ts 中注册：

import { createApp } from 'vue'
import App from './App.vue'
import { createPinia } from 'pinia'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')

3. 路由配置 —— Vue Router 4 + TypeScript

安装依赖：

npm install vue-router@4

基本配置：

// src/router/index.ts
import { createRouter, createWebHistory } from 'vue-router'
import Home from '../views/Home.vue'

const routes = [
  {
    path: '/',
    name: 'Home',
    component: Home
  },
  // 更多 route...
]

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes
})

export default router

4. 接口请求封装（Axios + Interceptor）

// src/utils/request.ts
import axios from 'axios'

const service = axios.create({
  baseURL: '/api',
  timeout: 5000
})

service.interceptors.request.use(config => {
  const token = localStorage.getItem('token')
  if (token) config.headers['Authorization'] = `Bearer ${token}`
  return config
})

service.interceptors.response.use(response => {
  return response.data
}, error => {
  console.error('API Error:', error)
  return Promise.reject(error)
})

export default service

调用方式：

import request from '@/utils/request'

async function fetchUserInfo() {
  const res = await request.get('/user/info')
}

5. 样式部分：Sass + PostCSS 自动补全

安装依赖：

npm install sass postcss autoprefixer --save-dev

postcss.config.js：

module.exports = {
  plugins: {
    autoprefixer: {},
    'postcss-pxtorem': {
      rootValue: 37.5,
      propList: ['*']
    }
  }
}

这样就能让 CSS 兼容 IE11 并自动适配移动端 rem 布局。

---

踩坑经验：那些深夜修复的小事

1. IE11 兼容性问题

虽然现在很多人都说“别管 IE”，但我们确实遇到了必须支持的需求。以下是几个常见的兼容点：

• 使用 Babel 编译 ES6+ 语法
• 手动添加 polyfill 到 vite.config.js 的 define 字段中
• 移除所有箭头函数中的隐式返回（比如 .map(x => x * 2)），IE 不识别
• 使用 postcss-preset-env 来支持现代 CSS 写法

配置样例：

optimizeDeps: {
  esbuildOptions: {
    target: 'es2015'
  }
}

2. 组件命名冲突导致页面空白

Vue 单文件组件中有个很容易忽略的细节：不要让组件名和原生标签名重复。

比如定义一个组件叫 <Input />，如果你同时在某个地方用了 HTML 原生的 <input> 标签，可能会触发某些诡异的渲染异常，页面直接空白。

解决方式：组件命名加上大写字母或前缀，如 <BaseInput /> 或 <MyInput />。

3. 接口请求跨域问题

本地开发时接口路径是 /api/user，但在生产环境部署到了二级域名，导致跨域。

解决方案是在 vite.config.js 加入代理设置：

server: {
  proxy: {
    '/api': {
      target: 'https://your-api-server.com',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}

这样开发阶段就可以正常访问线上服务，避免 mock 数据带来的偏差。

---

效果总结：项目上线后带来了什么？

项目正式上线三个月后，回顾一下我们的收益：

• 首次加载速度控制在 2s 以内（gzip 后主包体积约 800KB，分块加载）
• 团队协作顺畅：TypeScript 让新人上手更快，状态逻辑清晰可控
• 迭代速度快：有了合理的组件拆分和封装，新增功能平均只需 1~2 天
• 可维护性强：借助 Storybook 文档化，组件复用率高达 60%+
• 兼容性过关：顺利通过 IE11 测试，无重大样式问题

最关键的是，我们避免了“边开发边重构”的噩梦，整个项目周期都很平稳。

---

经验分享：给你的建议

1. 合理取舍工具链，不要盲目跟风

   • 不要为了“新技术”而强行引入一堆工具，要考虑团队接受度和后期维护成本
   • Vite 很好，但如果是老项目，Webpack 可能更稳妥

2. 尽早制定编码规范

   • ESLint + Prettier 不只是格式化工具，更是代码一致性保障
   • 建议团队统一使用 VSCode 插件，并设置保存时自动格式化

3. 接口与UI分离，提前Mock

   • 利用 Mock.js 或 JSON Server 模拟数据，避免等待接口开发耽误进度
   • 前端工程师也应具备一定的接口设计能力

4. 关注用户体验和性能细节

   • 使用 Suspense 异步加载组件
   • 图片懒加载、骨架屏、防抖节流这些小技巧都能带来不错的体验提升

5. 重视测试和 CI/CD

   • 即使是小项目，也应该写单元测试（推荐 Vitest）
   • 配置 GitHub Actions 实现自动打包部署

6. 学会借力工具

   • 推荐的开发工具：VSCode + DevTools + Storybook + Vue Devtools
   • 性能分析可以用 Lighthouse 提供的数据作为依据

---

最后一点感想

从零开始搭项目，其实是一个特别锻炼人的过程。它不仅仅考察你的技术深度，更考验你对项目全局的把握和对细节的敏感度。

这期间我也曾无数次怀疑自己：是不是选错了框架？代码组织是不是不够优雅？有没有更好的方案？但正是这些焦虑和自省，让我逐渐建立起一套属于自己的前端工程观。

所以如果你也在准备开始一个新的前端项目，请相信你自己。只要方向正确，坚持下来，总会看到结果的。

希望这篇文章对你有所帮助，有任何想法欢迎留言交流！