项目做了一半想重写？这套前端架构让你少走3年弯路

你是不是经历过项目写到一半发现目录乱成毛线组件互相依赖改一个地方崩十个地方。想重写老板说“没时间”。不重写每天加班改bug。今天我们就来聊聊前端架构——不是大厂才需要的东西而是让你的项目能撑过3年迭代的“骨架”。看完你就能搭出一个即使团队换了几拨人代码依然整洁的项目。前言盖房子要先打地基、搭框架再砌墙、装修。前端也一样。很多人上来就写组件写到一半发现状态管理乱、API调用散落各处、样式冲突、路由不知道怎么组织……最后项目就像一栋歪歪扭扭的危房加个新功能都怕塌。架构不是“过度设计”而是让你在项目初期花20%的时间省掉未来80%的痛苦。今天我们就从零开始搭一套能支撑中大型项目的前端架构。一、技术选型别跟风看需求架构的第一步是选技术。但记住没有最好的技术只有最合适的。1. 框架选什么React生态最丰富适合复杂交互、需要高度定制化的项目。学习曲线平缓但需要自己搭配路由、状态管理。Vue上手快模板直观适合中小项目或团队以Java/PHP为主。官方生态完整Vue Router、Pinia。Angular大而全适合大型企业级应用但学习曲线陡峭。建议如果不是特殊需求React或Vue二选一。团队熟悉哪个用哪个。2. 状态管理React简单项目用Context useReducer中等项目用Zustand轻量大项目用Redux Toolkit。VueVue 3 推荐 Pinia比Vuex更简单。3. 构建工具Vite首选快。除非你要兼容IE或需要特殊插件否则别用Webpack了。4. 类型系统TypeScript必选。别犹豫就算小项目也能减少一半的运行时bug。5. UI组件库内部后台系统Ant Design、Element Plus、Semi Design。面向C端需定制自己封装基础组件库或用Tailwind CSS 无头组件Headless UI。二、目录结构一眼就知道代码在哪一个好的目录结构新人进来10分钟就能找到要改的文件。推荐分层结构以React为例src/ ├── api/ # API请求层 │ ├── request.ts # axios实例配置 │ ├── user.ts # 用户相关接口 │ └── product.ts ├── assets/ # 静态资源图片、字体 ├── components/ # 通用组件按钮、弹窗、表格 │ ├── Button/ │ │ ├── index.tsx │ │ ├── Button.module.css │ │ └── types.ts │ └── Modal/ ├── hooks/ # 自定义Hooks ├── layouts/ # 布局组件Header、Sidebar ├── pages/ # 页面组件按路由划分 │ ├── Home/ │ ├── User/ │ │ ├── List.tsx │ │ ├── Detail.tsx │ │ └── components/ # 页面私有组件 │ └── ... ├── router/ # 路由配置 ├── store/ # 全局状态Redux/Zustand ├── styles/ # 全局样式、主题变量 ├── types/ # 全局TS类型定义 ├── utils/ # 工具函数日期格式化、校验、存储 └── main.tsx # 入口原则按功能/模块划分不是按文件类型不要把所有css放一个目录。通用组件放components页面独有组件放在页面目录下的components。API按业务模块拆分不要一个api.ts放几百行。三、API层统一管理妈妈再也不怕接口乱飞很多项目直接在组件里写fetch(/api/user)导致接口地址散落各处改个域名要替换几十个文件。正确姿势封装API层。// api/request.tsimportaxiosfromaxios;constrequestaxios.create({baseURL:import.meta.env.VITE_API_BASE_URL,timeout:10000,});// 请求拦截器加token、loading等request.interceptors.request.use(config{config.headers.AuthorizationBearer${getToken()};returnconfig;});// 响应拦截器统一错误处理、数据解构request.interceptors.response.use(resres.data,err{if(err.response?.status401){// 跳转登录}returnPromise.reject(err);});exportdefaultrequest;// api/user.tsimportrequestfrom./request;exportconstgetUserInfo(id:number)request.get(/user/${id});exportconstupdateUser(data:User)request.put(/user,data);组件里只调用getUserInfo不关心底层用axios还是fetch。四、状态管理策略别把所有东西都放全局组件内部状态useState。跨组件但非全局Context或Zustand的小store。全局共享用户信息、主题、权限Redux/Pinia。服务器状态缓存、请求状态React Query / Vue Query推荐比手动管理loading、error、重试方便得多。五、路由设计懒加载 权限控制使用动态import()实现路由懒加载减少首屏体积。封装一个AuthRoute组件根据用户权限重定向或显示403。// router/index.tsx const routes [ { path: /dashboard, component: lazy(() import(/pages/Dashboard)), meta: { requiresAuth: true, roles: [admin] } } ]; // 在Router组件里统一拦截六、样式方案别让CSS互相打架CSS Modules简单、无侵入、类型安全。Tailwind CSS快速开发但团队需要适应。CSS-in-JSstyled-components动态样式方便但运行时性能稍差。BEM命名 SCSS传统但稳定。推荐CSS Modules SCSS或Tailwind 普通CSS。七、错误处理与日志全局错误边界React的ErrorBoundary捕获组件渲染错误。API错误统一处理在axios拦截器里做。开发环境用console生产环境禁用或上报。if(import.meta.env.PROD){console.log(){};console.warn(){};}八、代码规范与Git HooksESLint配置plugin:typescript-eslint/recommended。Prettier统一格式化。Husky lint-staged提交前自动lint和格式化。Commitlint规范commit信息如feat: xxx、fix: xxx。九、环境配置与构建优化使用.env文件区分开发、测试、生产环境。Vite配置别名指向src。生产构建开启terser压缩、rollup-plugin-visualizer分析包体积、代码分割splitChunks。十、总结架构是不断演进的没有完美的架构只有适应当下团队的架构。但一个好的架构应该有这些特征新人上手快目录清晰命名规范。可扩展加新功能不破坏旧代码。可维护修改一处不需要改十处。可测试模块解耦依赖注入。别等到项目烂了才想重构。从第一天起花点时间搭好架子后面你会感谢自己。如果你觉得今天的“架构课”够干货点个赞让更多人看到。明天我们将开启一个新系列——性能优化实战从首屏加载到运行时优化让你的页面快到飞起。我们明天见