从零开始构建一个现代化前端项目
从零搭建一个现代化前端项目：一个老码农的实战分享
大家好，我是小李。做过不少前端项目，从最初用 jQuery 撸页面到现在用 React、Vue 打天下的这些年，前端技术变化真的太快了。今天我想聊聊最近一次从零开始构建一个现代化前端项目的全过程——不是那种“hello world”的教程，而是结合真实业务场景，把遇到的坑、踩过的雷，以及最终的解决方案都原原本本地记录下来。
这不仅是一次技术选型的过程，更是一场对开发流程、协作模式、工程化建设的深度思考。希望通过这次分享，能给大家带来一些真正有用的经验。
一、项目背景：我们为什么要重新启动一个前端项目？
上个月，公司接了一个新客户，是一家做供应链管理的中型企业。他们目前有一套传统的后台系统，界面老旧、交互复杂，用户反馈非常差。他们希望我们帮忙重构整个前台系统，并且目标是迁移到 Web 平台，方便后续扩展和维护。
原本这个项目准备直接基于之前的旧系统改造，但评估后发现技术债太多，很多组件难以维护，代码结构混乱。最后决定从零搭建一个新的前端项目，彻底更换技术栈，以提升用户体验、增强可维护性，并为未来的技术演进预留空间。
项目的核心需求包括：
- 用户界面要现代、易用、响应式布局；
- 支持复杂的表单操作与数据展示；
- 多个模块之间要有良好的状态管理和路由控制；
- 要适配移动端（至少在平板上可用）；
- 开发团队有三人，要求有清晰的开发规范与协作机制；
- 需要支持国际化和深色主题切换；
- 性能要稳定，加载速度尽可能快。
当时我负责前端技术选型和工程搭建，这是我第一次独立主导整个项目架构的设计，压力不小，但也收获颇丰。
二、问题描述：我们在构建过程中遇到了哪些挑战？
1. 技术栈的选择困难症
虽然现在主流框架不少，React 和 Vue 都很成熟，但我们之前主要用的是 Vue，所以一开始打算继续使用 Vue3 + Vite。不过后来发现客户可能有长期维护的需求，而他们内部团队也有人熟悉 React，最终折中选择了 React + TypeScript + Vite 的组合。
感悟：技术选型不仅要考虑当前团队的技能储备，还要看是否有利于客户的持续维护。
2. 国际化和主题配置怎么整？
早期只是用了 react-i18next 来处理国际化，但在后期加上深色模式时发现状态管理有点乱，各个模块都需要订阅主题和语言状态，而且切换时有些页面状态没更新，用户体验不佳。
3. UI 组件库如何选择？
我们调研了好几个 UI 库，Ant Design、Material UI、Chakra UI，各有优劣。最终为了节省定制成本，还是选了 Ant Design（Pro Components 也很香），同时配合 Tailwind CSS 实现更灵活的样式覆盖。
4. 开发效率如何保障？
多人协作，如果没有统一的规范和自动化流程，项目很容易失控。我们一开始没有引入 ESLint + Prettier + Husky + lint-staged，导致代码风格不统一，后面不得不花时间补课。
5. 性能优化怎么做？
页面加载初期资源体积过大，特别是图表和大表格组件，严重影响用户体验。首屏加载时间一度超过 5 秒，必须优化。
三、我们的解决方案：从零到一的技术选型与工程实践
🌟 技术栈最终确定如下：
| 类别 | 工具/框架 |
|---|---|
| 构建工具 | Vite + SWC（用于更快的 TS 编译） |
| 核心框架 | React 18 + TypeScript |
| 状态管理 | Zustand（轻量级替代 Redux） |
| 路由 | React Router v6 |
| UI 框架 | Ant Design + Tailwind CSS |
| 国际化 | react-i18next |
| 表单 | React Hook Form |
| 图标 | Iconify + @iconify/json |
| 样式方案 | SCSS + Tailwind CSS |
| 工程规范 | ESLint, Prettier, Husky, lint-staged |
| 部署 | GitHub Actions 自动部署到 Vercel |
🛠️ 工程结构设计
src/
├── assets/ // 静态资源
├── components/ // 公共组件
├── hooks/ // 自定义 hooks
├── layouts/ // 页面布局结构
├── pages/ // 页面组件
├── services/ // 接口调用
├── stores/ // 状态管理
├── themes/ // 主题变量
├── utils/ // 工具函数
├── i18n/ // 国际化文案
├── App.tsx // 根组件
└── main.tsx // 入口文件
我们采用了类似 Next.js 的目录结构，这样后期如果迁移也不需要太大改动。
四、关键代码片段和配置示例
✅ 使用 Vite + SWC 提升编译速度
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
export default defineConfig({
plugins: [react()],
})
比默认的 Babel 方案提速约 30%，特别是在热重载的时候。
✅ 使用 Zustand 做状态管理
// stores/themeStore.ts
import { create } from 'zustand'
interface ThemeState {
darkMode: boolean
toggleDarkMode: () => void
}
export const useThemeStore = create<ThemeState>((set) => ({
darkMode: false,
toggleDarkMode: () => set((state) => ({ darkMode: !state.darkMode })),
}))
比 Redux 更简洁，适合中小型项目。
✅ 国际化 + 主题联动
// i18n/index.ts
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import LanguageDetector from 'i18next-browser-languagedetector'
import resources from './resources'
i18n.use(LanguageDetector)
.use(initReactI18next)
.init({
resources,
fallbackLng: 'en',
interpolation: {
escapeValue: false,
},
})
export default i18n
然后通过 context 或 zustand 将语言变更与主题同步。
✅ 使用 Tailwind CSS 和 Ant Design 联合定制主题
/* tailwind.config.js */
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
theme: {
extend: {
colors: {
primary: '#1677ff',
secondary: '#e6e6e6',
},
},
},
plugins: [],
}
Ant Design 的变量通过 Less 文件全局覆盖。
五、踩坑经验分享
⚠️ 踩坑点1：ESLint 初始未集成，后期整合困难
我们一开始忽略了代码规范，等中期发现问题再集成 ESlint 时，发现大量报错，修改代价高。建议一开始就引入规范：
npm install eslint prettier eslint-config-prettier eslint-plugin-react @typescript-eslint/eslint-plugin @typescript-eslint/parser --save-dev
并创建 .eslintrc.cjs 和 .prettierrc 文件。
⚠️ 踩坑点2：国际化插件在动态加载时未触发组件刷新
一开始我们用了懒加载的翻译资源，但在某些组件中语言切换后界面没有立即更新。解决方式是在组件里用 useTranslation 的 reload 方法手动触发刷新。
const MyComponent = () => {
const { t, i18n } = useTranslation()
useEffect(() => {
const handleLanguageChange = () => {
// 可以在这里触发重新渲染逻辑
}
i18n.on('languageChanged', handleLanguageChange)
return () => {
i18n.off('languageChanged', handleLanguageChange)
}
}, [i18n])
}
⚠️ 踩坑点3：Vercel 部署时 SSR 异常（我们用了 CSR）
起初误以为 Vercel 默认支持 React Server Side Rendering，结果页面加载时白屏或者静态资源路径错误。后来调整了部署命令，确保所有资源打包正确上传即可解决问题。
六、效果总结：项目上线后的成果
经过两个月的努力，我们完成了第一期项目交付：
- 性能显著提升：首屏加载从原来的 5s 减少到 1.2s。
- 国际化的支持良好：中英文无缝切换，无卡顿。
- 代码结构清晰：借助 TypeScript + ESLint，BUG 明显减少。
- 跨平台兼容性增强：PC 和平板端都能流畅运行。
- 团队协作顺畅：通过 husky 在提交前检查，避免了很多低级错误。
客户反馈也非常积极，说新的系统看起来专业、用起来顺手，提升了整体品牌形象。
七、我的几点建议与注意事项
作为这次项目的主负责人，我有几点真心建议想送给正在起步或者准备重构前端项目的朋友：
🔧 1. 尽早定下工程规范
即使是一个小项目，也要提前准备好 ESLint、Prettier、Git Hooks 等工具链。否则后期整合太痛苦了。
🌐 2. 不要忽视浏览器兼容性和性能优化
即使是新项目，也不能只考虑 Chrome 最新版。比如我们一开始用了太多 CSS 变量和现代特性，在 Safari 上出现了样式失效的情况，不得不降级部分写法。
🔄 3. 状态管理要根据项目规模来选型
Zustand 足够应对大部分中小型项目；Redux Toolkit 适合大型项目；MobX 不推荐新人直接上手。
🛡️ 4. 合理使用第三方依赖，别贪多
我们一开始装了十几个 UI 库和工具包，后来发现根本用不到，还影响打包体积。后来一一剔除，保留必要的核心依赖，性能立竿见影。
💡 5. 调试工具一定要会用
Chrome DevTools、React Developer Tools、Vite Preview 都是非常实用的工具，帮你快速定位问题。
写在最后：前端不只是写页面，更是产品思维的体现
在这次从零开始的过程中，我深刻体会到前端开发早已不仅仅是“写页面”。它涉及到产品体验、工程规范、性能优化、团队协作等多个维度。而一个好的前端架构，不仅能提高开发效率，更能直接影响用户的使用感受。
也许你会问：为什么我要费这么大劲从零开始？而不是基于现有模板？
我想说：正因为是从零开始，你才更了解每一块是怎么拼起来的。每一个细节都是你亲手打磨的，这样的项目才有灵魂。
如果你也正在做一个全新的前端项目，不妨试试这些做法。希望能帮你在路上少走点弯路，多一点成就感。
祝你们项目顺利，bug 少少，代码优雅！
💬 如果你也经历过类似的项目经历，欢迎留言交流！咱们一起成长，一起写出更好的代码。
评论 0