从“一张白纸”开始构建一个现代化前端项目：我的实战经历分享

作为一名在互联网公司工作的前端开发者，我曾参与过多个从0到1的前端项目搭建。其中有一个项目让我印象深刻，因为它不仅涉及到技术选型、架构设计、团队协作这些“硬核”的问题，还考验了我们对产品需求的理解与实现能力。

这篇文章我想以亲身经历为基础，分享一下我当时是如何从头开始构建一个现代化前端项目的——包括我在过程中遇到的挑战、决策背后的原因、踩过的坑，以及最终成果给团队带来的价值。

希望这篇文章能够给正在准备或刚刚开启新项目的你一点启发和帮助。

一、为什么要做这个项目？

故事要回到两年前。当时我们所在的业务线需要开发一个新的运营后台系统，目标是给客户经理提供一个统一的工具平台，涵盖数据看板、客户管理、活动配置等功能模块。

虽然看起来这只是一个常规的管理后台，但由于：

• 需要支持大量高频交互的数据展示；
• 要覆盖主流浏览器，同时兼顾低版本IE11（历史原因）；
• 系统需要持续迭代更新，并预留良好的扩展性；
• 未来可能会接入微前端来与其他系统整合；

所以我们意识到，不能用那种“临时搭起来先上线再说”的方式来做这件事。必须在一开始就把基础打扎实，构建一个具备现代特性的前端项目体系。

二、开搞之前：技术选型是关键

在正式编码前，我们要做的第一件事就是确定项目的技术栈和开发流程。这一步非常关键，因为后续所有的开发、部署、维护都将围绕着它展开。

我们做了哪些调研？

我们在内部拉了一个小团队，用了大约一周的时间进行了技术方案的比对和讨论。我们主要考虑以下几个方面：

考察维度	内容说明
框架选择	Vue vs React vs Angular
构建工具	Vite 还是 Webpack？
状态管理	Pinia / Vuex / Redux
组件库	自研组件 or Ant Design / Element Plus / Naive UI
工程化规范	Eslint + Prettier + Git 提交规范等
包体积优化	代码拆分、按需加载
浏览器兼容性	是否需要支持 IE11
国际化方案	i18next / vue-i18n

经过几轮讨论后，我们最终定下来的核心技术栈如下：

• 框架：Vue 3（基于 Composition API 开发）
• 状态管理：Pinia
• UI 组件库：Element Plus（按需导入 + 自定义主题）
• 工程化工具：
  • 开发环境：Vite
  • 构建打包：Webpack
• 样式方案：SCSS + BEM 命名规范
• TypeScript：全项目启用
• 国际化：vue-i18n（配合 json 管理翻译资源）

选择这套组合主要是出于以下几个考量：

1. Vue 3 的性能提升和更优雅的 Composition API，加上国内使用率高，学习曲线适中；
2. Pinia 相比 Vuex 更加简洁易用，且天然支持 Vue 3；
3. 我们团队对 Element Plus 更熟悉，而且它本身就提供了很好的按需引入机制；
4. TypeScript 可以帮助我们在项目早期就建立良好的类型约束，减少后期重构成本；
5. 兼顾 IE11 是个痛，但也只能通过 Polyfill 和部分降级策略去应对。

三、开工！初始化项目结构

接下来，我们就开始正式创建项目骨架。这一步其实挺重要的，因为它决定了整个项目后期是否好维护、团队成员是否容易上手。

使用 Vite 快速创建基础模板

npm create vite@latest my-admin -- --template vue-ts

执行命令之后，Vite 会帮我们生成一个包含 Vue 3 + TS 的初始目录结构。但光靠这些还不够，我们还需要做一些改造。

改造后的典型目录结构

src/
├── assets/          # 静态资源
├── components/      # 公共组件
├── layouts/         # 布局组件（如顶部导航栏、侧边栏等）
├── pages/           # 页面视图
├── router/          # Vue Router 配置
├── store/           # Pinia Store 管理
├── services/        # 数据请求封装
├── utils/           # 工具函数
├── locales/         # 多语言包文件
├── App.vue
└── main.ts

这样组织结构的好处是层次清晰，分工明确，尤其适合多人协作。

添加基础功能依赖

接下来安装一些必要的插件和依赖：

npm install vue-router pinia @pinia-plugin-persistedstate element-plus dayjs axios mockjs vue-i18n

然后分别配置：

• Element Plus 插件注册
• Vue Router 的懒加载路由设置
• Pinia Store 初始化及持久化插件集成
• axios 封装拦截器 & mock 数据支持
• 多语言文件管理逻辑

集成 TypeScript 类型路径别名

为了更好地支持 TypeScript，我们在 tsconfig.json 中添加了路径映射：

{
  "compilerOptions": {
    ...
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  ...
}

然后配合 VSCode 的自动跳转（Command/Ctrl + 点击），开发效率大大提升。

四、遇到的第一个挑战：IE11 支持难题

在开发过程中，我们很快遇到了第一个棘手的问题：如何让 Vue 3 + TypeScript 的项目在 IE11 上正常运行？

说实话，这个问题一度让我们很头疼。

问题现象

• 在 Chrome 等现代浏览器上一切正常；
• 但在 IE11 上页面空白，没有任何报错；
• 控制台输出了一堆语法错误（比如无法识别 import, const, 箭头函数 等）。

问题分析

虽然 Vite 默认是为现代浏览器服务的，但我们项目又不得不支持 IE11。因此，我们需要对构建工具链进行调整。

解决方案

1. 改用 Webpack 构建生产环境
   • Vite 本身不支持 IE11，所以开发时依旧使用 Vite，但构建部署的时候切换为 Webpack。
2. Babel 预设转换 ES6+ 代码

   npm install --save-dev @babel/core @babel/preset-env babel-loader core-js
   

   然后在 Webpack 的 loader 配置里加入：

   {
     test: /\.js$/,
     loader: 'babel-loader',
     options: {
       presets: ['@babel/preset-env']
     }
   }
   

3. 手动引入 polyfill

   // src/main.ts
   import 'core-js/stable'
   import 'regenerator-runtime/runtime'
   

4. 关闭 Tree-shaking 对 IE 的影响 设置 sideEffects: false 或者指定某些依赖不要被 Tree-shake 掉，避免出错。

小插曲

还记得那次测试上线前的一次联调吗？测试同学反馈首页在 IE11 上点不动按钮，控制台也没啥有用信息。排查了整整一下午才发现是一个第三方组件用了 Proxy，而 IE 完全不支持……最后还是换成低配版写法才搞定。

五、组件复用与可维护性设计

随着页面数量增加，我们发现很多功能模块存在重复代码，尤其是在表格、表单和弹窗组件上。于是我们决定做一件事：提炼公共组件库，建立自己的通用组件集合。

我们的思路

我们将常用的 UI 元素抽象成独立组件，并加上合理的 props 接口：

例如，我们打造了一个 BaseTable.vue 组件，支持：

• 分页；
• 表格列自定义；
• 排序；
• 数据筛选；
• 多选等功能。

通过这样的方式，各个页面引用该组件即可快速搭建功能齐全的表格界面。

同时我们还建立了统一的设计规范文档（虽然只是内部 Wiki 页面），规定命名规则、组件用法和注意事项。

成果

• 减少重复开发时间约 30%；
• 降低了新人接手项目的门槛；
• 后期维护更加轻松（一处修改全局生效）。

六、性能优化：不只是更快，还要更稳

当项目功能越来越多，我们开始关注起整体的性能表现。

性能优化的方向

我们从几个角度入手：

1. 拆包优化

• 使用 Webpack 的 splitChunks 功能，将公共代码抽离；
• 对大型组件或路由模块采用异步加载（动态导入）；
• 第三方库尽量做到按需引入（比如 Element Plus 配合 unplugin-vue-components 插件）；

2. 图片压缩与懒加载

• 引入 v-lazy 指令（结合 vueuse/lazy）；
• 图片全部走 CDN 并使用 WebP 格式；

3. 缓存策略

• 利用本地缓存接口数据（localStorage + 时间戳判断）；
• 对频繁触发的事件做防抖节流处理（如搜索输入框、resize 等）；

4. 利用 DevTools 分析瓶颈

• 通过 Chrome Performance 面板，找出长任务、资源加载慢的地方；
• 结合 Lighthouse 报告，评估整体评分和改进方向；

小技巧：Chrome Performance 面板的妙用

有一次，我们发现某个页面首屏加载特别慢。后来用 Performance 工具一看，原来是某段日志打印占用了主线程超过 3 秒 😂

果断砍掉那段调试代码后，FPS 直接飙升。

七、开发体验与协作规范

除了代码本身的质量，良好的开发流程和协作机制也很重要。

我们做了这些事：

• Git 提交规范：使用 Conventional Commits，结合 Husky + Commitlint；
• 代码风格统一：Eslint + Prettier + EditorConfig；
• CI 自动化检查：在合并 PR 前跑一遍 lint 和 typecheck；
• VSCode 插件推荐：Volar、ESLint、Prettier、TypeScript Hero 等；

此外，我们在项目初期就制定了一份简单的《团队开发规范》，涵盖变量命名、组件命名、目录划分建议等内容。

团队协作的小感悟

有一段时间我们遇到一个问题：不同人写的组件之间样式冲突严重，特别是 SCSS 变量和类名。后来我们制定了两个规则：

1. 所有组件样式的外层容器必须使用唯一的 BEM 格式命名；
2. 使用 scoped 样式，并配合 CSS Modules 对局部样式做隔离。

这两个改动显著减少了样式污染问题。

八、收获与展望

这个项目最终顺利上线并稳定运行至今，期间经历了多次迭代和重构，也成为了我们内部另一个新建项目的参考模板。

最大的收益点包括：

• 开发效率明显提升：模块化、组件化让我们可以高效复用已有功能；
• 可维护性增强：结构清晰，类型安全，便于后期迭代；
• 跨浏览器支持良好：即使面对老旧的 IE11 也有稳定的兼容方案；
• 为后续扩展留足空间：项目结构具备良好的拓展性和模块化特性。

展望未来

如今，我们的项目已经逐步接入微前端方案，未来也会尝试更多前沿技术，比如：

• 使用 Vite + Module Federation 实现更灵活的远程组件通信；
• 推广 Serverless 服务端渲染（Nuxt 3 + Nitro）提升 SEO；
• 探索 Zustand-like 方案简化状态管理；
• 增强可视化图表能力（ECharts / D3.js）；

九、给读者的一些建议

如果你也在准备或者正在做一个新的前端项目，以下是我总结的一些经验，希望能对你有所帮助：

1. 技术选型要贴合业务场景，而不是一味追求新技术；
2. 一开始就重视工程化，规范化能省下后期大量的沟通和修复成本；
3. 优先写可维护、可读性强的代码，而不是只求快；
4. 多站在用户视角思考交互细节和体验优化；
5. 善用 DevTool，善用 Linter 工具和自动化脚本；
6. 记录每一个值得总结的经验，哪怕是“踩坑日记”，都是一笔财富。

---

写到这里，突然想到刚进公司那会儿，前辈告诉我的一句话：“写前端，不是写页面，而是写用户体验。”现在回头看，这句话说得真到位。

希望这篇来自一线实战的文章，能够成为你构建自己现代化前端项目时的一个实用指南。欢迎留言交流，我们可以一起成长！

如果你觉得这篇文章有帮助，请点赞、收藏或转发，你的鼓励是我继续分享的动力 👇😊