企业官网建设流程全解析

1. 前端技术架构到底在解决什么问题

很多人第一次听到“前端技术架构”这个词，脑子里浮现的可能是Webpack配置、Vue或React的目录结构，甚至觉得这就是个“高级脚手架”的代名词。但如果你真正在团队里扛过一个中型以上的前端项目，就会明白：架构要解决的核心问题从来不是“用哪个框架”，而是当业务需求以周为单位膨胀、参与的人从3个变成30个的时候，代码怎么还能改得动、发得出去、查得到问题。

我见过太多项目起步时干净利落，半年后变成“改一个按钮颜色要翻六个文件、跑三遍构建、还得问三个人”的泥潭。这不是开发者水平不行，而是架构在项目演进过程中没有跟着长。前端技术架构的本质，是一套约束与分工的机制：它规定了代码放在哪里、依赖怎么流动、状态归谁管、构建产物如何组织、多人协作时边界在哪里。框架只是这套机制里最容易被替换的一个零件。

这篇文章适合三类人看：一是刚接手一个存量项目、想理清头绪的开发者；二是准备从零搭建项目、不想三个月后推倒重来的技术负责人；三是对架构有模糊认知、想系统梳理一遍的进阶前端。我会从分层设计、构建体系、状态管理、微前端与模块联邦、性能与监控这几个维度，把一套能落地的架构思路拆开讲，中间穿插我自己踩过的坑和实际取舍逻辑。全文不绑定任何具体业务，讲的是通用方法论，你可以直接对照自己的项目做体检。

需要先明确一个前提：没有万能架构，只有匹配当前团队规模和业务节奏的架构。三个人的团队搞微前端是自残，三十个人的团队共用一个仓库不做分层是灾难。所以下面每一块内容，我都会告诉你“什么阶段该上、什么阶段别碰”。

2. 分层设计：把“改哪里”变成一道有标准答案的题

2.1 为什么大多数项目的目录结构会失控

先看一个典型现象。项目初期目录是这样的：src/components、src/pages、src/utils、src/api。看起来挺清楚。三个月后，components里混进了业务组件、通用组件、临时组件；utils变成了一个什么都往里塞的垃圾桶；api里既有请求封装又有数据转换还有mock。新人进来问“用户头像组件在哪”，没人答得上来，因为有三个地方都可能有。

失控的根因不是命名不规范，而是目录结构只按“技术类型”分层，没有按“职责边界”分层。技术类型分层（组件、工具、接口）在项目小的时候够用，一旦业务复杂度上来，同一类型下的东西彼此毫无关系，找起来全靠记忆和搜索。正确的做法是引入领域分层，让目录结构直接反映业务模块的边界。

2.2 一套可落地的四层结构

我目前比较推荐、也在多个项目验证过的分层方式是这样的：

• 应用层（app）：负责路由注册、全局Provider、启动逻辑。这一层只做组装，不写业务。
• 页面层（pages）：按路由维度组织，每个页面是一个独立目录，内部可以有自己的子组件、hooks、样式。页面层是业务逻辑的主要承载地。
• 领域层（features 或 domains）：把跨页面复用的业务能力抽出来，比如“用户权限”“订单状态机”“消息通知”。这一层是架构的核心，它决定了业务能力能不能被复用而不是复制。
• 基础层（shared）：纯技术无关的通用能力，UI组件库、请求库封装、工具函数、类型定义。这一层不允许依赖上面任何一层。

依赖方向必须是单向的：app → pages → features → shared。任何反向依赖都是架构腐化的开始。我见过页面层直接引用另一个页面的内部组件，短期省事，长期就是改A崩B。

提示：判断一个模块该放哪层，问自己一句话——“如果把这个业务整个删掉，这个模块还需要存在吗？”需要，就往基础层或领域层放；不需要，就留在页面层。

2.3 用约束工具把分层“焊死”

光靠口头约定没用，人一忙就忘了。必须用工具强制。最直接的两个手段：

第一，配置路径别名并配合ESLint的import/no-restricted-paths规则，禁止低层引用高层。比如在.eslintrc里配置禁止shared目录import任何features或pages的内容。这样一旦有人写错，提交前就会报错。

第二，用dependency-cruiser做依赖关系可视化与校验。它能生成依赖图，也能配置规则文件，把“禁止循环依赖”“禁止跨层引用”写成可执行的检查项，挂到CI里。下面是一段规则配置示例：

// .dependency-cruiser.js 片段 module.exports = { forbidden: [ { name: 'no-circular', severity: 'error', from: {}, to: { circular: true } }, { name: 'shared-cannot-import-features', severity: 'error', from: { path: '^src/shared' }, to: { path: '^src/(features|pages|app)' } } ] };

这套东西刚上的时候团队会有点抵触，觉得束手束脚。但跑一个月后，所有人都会感谢它——因为再也不会出现“改一个工具函数导致三个页面白屏”的事故了。

2.4 分层带来的实际收益与代价

收益很直接：新人上手时间从两周缩短到三天，因为目录结构本身就是一张业务地图；代码评审时争论“这个文件该放哪”的时间大幅减少；重构时可以放心地整目录迁移，因为依赖边界清晰。

代价也要说清楚：前期搭建成本高，需要有人专门设计并维护规则；小项目（页面少于10个）上这套结构会显得过度设计，反而增加心智负担。我的经验是，页面数量超过15个、或者团队超过5个人，就该认真考虑分层；低于这个规模，用简单的components/pages/utils三件套就够了，别为了架构而架构。

3. 构建体系：从“能跑就行”到“可控可观测”

3.1 构建工具选型的真实决策逻辑

现在构建工具的选择很多，Vite、Webpack、Rspack、Turbopack、esbuild各有拥趸。很多文章会列一堆性能对比表格，但实际选型时，性能只是其中一个维度。我通常按这个优先级判断：

我的实际结论是：新项目直接上Vite，开发体验和配置简洁度优势明显；存量Webpack项目不要为了快而盲目迁移，除非构建时间已经严重拖累迭代，否则迁移成本往往高于收益；对构建产物体积极度敏感的场景，可以在Vite基础上叠加Rspack做生产构建，但要做好插件兼容性测试。

3.2 构建配置里最容易被忽略的三件事

第一件是环境变量的管理。很多人直接在代码里写if (process.env.NODE_ENV === 'production')，然后不同环境靠改代码切换。正确做法是用.env文件加构建时注入，并且严格区分“构建时变量”和“运行时变量”。构建时变量（如API基础路径）在打包时就固化了，运行时变量（如动态配置）需要通过接口或全局对象注入。混用这两者，会导致同一个包在不同环境行为不一致，排查起来极其痛苦。

第二件是代码分割策略。默认的按路由分割只是起点。真正影响首屏的是“哪些代码必须同步加载、哪些可以懒加载”。我的经验是把第三方大依赖（图表库、富文本编辑器、地图SDK）全部做成动态import，并且用webpackChunkName或Vite的魔法注释给chunk起可读的名字，方便在产物分析里定位。

// 动态导入并命名chunk const ChartPanel = () => import(/* webpackChunkName: "chart-panel" */ './ChartPanel');

第三件是构建产物的可观测性。每次构建后自动生成体积报告，挂到CI的产物里。一旦某个chunk体积超过阈值就报警。我见过一个项目因为某次引入了一个日期库，首屏包体涨了200KB，两周后才被发现。用rollup-plugin-visualizer或webpack-bundle-analyzer生成报告，配合体积阈值检查，能把这类问题挡在合并之前。

3.3 多环境构建的工程化处理

真实项目至少有三个环境：本地开发、测试环境、生产环境。有些还有预发布、灰度。如果每个环境都靠手动改配置，迟早出事。我的做法是：

• 所有环境差异收敛到一个config目录，每个环境一个文件，导出同构的配置对象。
• 构建脚本通过--mode参数选择配置，CI流水线里不同分支对应不同mode。
• 敏感信息（如第三方key）绝不进仓库，通过CI的环境变量注入，构建时替换占位符。

这里有个坑要提醒：不要在构建配置里写业务判断逻辑。构建配置只负责“怎么打包”，不负责“打包成什么样给谁用”。业务差异应该通过运行时配置解决，否则构建配置会变成没人敢动的黑盒。

3.4 构建缓存与增量构建的实践

大型项目全量构建动辄几分钟，开发体验很差。缓存是必须的。Webpack的cache: { type: 'filesystem' }、Vite的依赖预构建缓存、以及CI层面的node_modules和构建产物缓存，三管齐下能把重复构建时间压到原来的三分之一以下。

但缓存有个经典陷阱：缓存失效判断不准导致产物不一致。我遇到过CI缓存了旧的构建产物，结果新代码没生效，测试环境跑的是老版本。解决办法是给缓存key加上源码的hash或者git commit id，确保代码变了缓存一定失效。宁可多花点时间重建，也不要出现“构建成功但产物是旧的”这种问题，它比构建慢可怕十倍。

4. 状态管理：别让全局状态变成全局污染

4.1 状态分类是选型的前提

一上来就问“用Redux还是Pinia还是Zustand”是错的。先分类：

• 组件本地状态：只在一个组件内用，useState或ref足够。
• 跨组件共享状态：同一页面内多个组件共享，用Context或provide/inject，或者提升到最近的公共父级。
• 全局应用状态：跨页面、跨层级共享，比如用户信息、主题、权限。这才需要状态管理库。
• 服务端状态：来自接口的数据，有缓存、失效、重新请求的需求。这类应该用专门的数据请求库（如TanStack Query、SWR），而不是塞进全局store。

把服务端状态塞进全局store是极常见的错误。接口数据有生命周期，全局store没有；接口数据需要按key缓存和失效，全局store只会越堆越大。分开处理之后，全局store往往能瘦身一半以上。

4.2 全局状态的最小化原则

我的原则是：全局store里只放三类东西——当前用户身份与权限、全局UI偏好（主题、语言）、跨页面共享的少量业务状态（如购物车）。其他一律不放。

为什么这么严格？因为全局状态每多一项，就多一个“谁都能改、改了不知道影响谁”的隐患。我接手过一个项目，全局store里有47个state字段，其中30个只有一两个组件在用。这种store已经不是状态管理，是状态垃圾场。

具体操作上，用模块化拆分store，每个模块只暴露必要的action，state通过getter读取而不是直接访问。以Pinia为例：

// stores/user.js export const useUserStore = defineStore('user', { state: () => ({ profile: null, permissions: [] }), getters: { isAdmin: (state) => state.permissions.includes('admin') }, actions: { async fetchProfile() { this.profile = await api.getProfile(); this.permissions = this.profile.permissions; } } });

组件里只调用userStore.isAdmin和userStore.fetchProfile()，不直接改state.permissions。这样状态的变更路径是收敛的，出问题能快速定位。

4.3 状态持久化与跨标签页同步

有些状态需要持久化，比如登录token、用户偏好。用pinia-plugin-persistedstate或手写localStorage同步都行，但要注意两点：一是只持久化必要的字段，不要把整个store序列化进去；二是处理版本迁移，当store结构变化时，旧的持久化数据要能兼容或安全丢弃。

跨标签页同步是另一个容易被忽略的场景。用户在A标签页退出登录，B标签页还显示着登录态。解决办法是监听storage事件，在store里做同步。这个细节不做，用户会觉得“这系统有bug”。

4.4 状态管理的反模式清单

最后列几个我踩过的反模式，供对照自查：

• 在action里直接操作DOM或调用路由跳转，导致状态逻辑和视图逻辑耦合。
• 用watch监听store变化去触发另一个store的action，形成隐式依赖链。
• 把表单的每个字段都放进全局store，其实用本地状态加提交时汇总更清晰。
• 在组件里直接修改store的state而不通过action，破坏可追踪性。

状态管理的目标不是“集中”，而是“可控”。集中但不可控，比分散更危险。

5. 微前端与模块联邦：什么时候该上，什么时候是坑

5.1 微前端解决的是组织问题，不是技术问题

先泼一盆冷水：如果你的团队只有一二十人、一个业务线，不要碰微前端。微前端的核心价值是让多个团队能独立开发、独立部署、技术栈自治。它带来的复杂度——样式隔离、路由协调、公共依赖共享、通信机制——在小团队里完全是负收益。

那什么时候该上？当出现这些信号时：多个团队维护同一个大应用但互相阻塞发布；不同业务模块需要不同技术栈且短期无法统一；主应用需要动态集成第三方提供的页面。这时候微前端才从“炫技”变成“刚需”。

5.2 主流方案的取舍逻辑

目前主流方案分两类：一类是运行时集成（如基于single-spa、qiankun、无界），主应用在运行时加载子应用；另一类是模块联邦（Module Federation），构建时或运行时共享模块。

运行时集成的优点是子应用完全独立，技术栈无关；缺点是通信和样式隔离需要额外处理，性能开销也更大。模块联邦的优点是共享依赖、通信自然；缺点是要求构建工具支持，且子应用之间耦合度相对更高。

我的实际选择是：如果子应用技术栈差异大、团队完全独立，用运行时集成；如果技术栈统一、只是想把大应用拆小，用模块联邦更轻。模块联邦在Vite和Webpack 5里都有成熟支持，配置也不算复杂。

5.3 微前端落地必须解决的四个问题

第一，样式隔离。子应用的全局样式会污染主应用。解决方案有Shadow DOM、CSS Modules、加前缀三种。Shadow DOM隔离最彻底但兼容性和调试体验有代价；加前缀最土但最稳。我一般推荐子应用强制使用CSS Modules或scoped样式，主应用做一层reset兜底。

第二，路由协调。主应用和子应用都可能操作URL。约定好谁负责哪段路径，子应用的路由basename由主应用注入，避免冲突。

第三，公共依赖共享。React、Vue这类框架如果每个子应用都打包一份，体积会爆炸。通过模块联邦的shared配置或运行时externals共享，但要注意版本一致性，版本不一致时共享会失败。

第四，通信机制。主应用和子应用之间传参、事件通知，要有统一约定。简单的用props和回调，复杂的用事件总线或状态共享。不要用全局变量，那是灾难。

5.4 一个务实的渐进式方案

如果团队还在犹豫，我建议走渐进路线：先把大应用按业务域拆成独立的npm包或monorepo子包，通过包管理共享，而不是一上来就搞运行时微前端。这样能先解决代码组织和复用问题，等团队和业务真的需要独立部署时，再往微前端演进。架构演进应该是被业务推着走，而不是被技术潮流拉着跑。

6. 性能与监控：架构的最后一公里

6.1 性能预算应该写进架构约束

性能不是上线前优化一下的事，它应该是架构的一部分。我习惯在项目初期就定下性能预算：首屏JS体积不超过200KB（gzip后）、首屏可交互时间不超过3秒（中端机型4G网络）、关键接口响应不超过500ms。这些数字写进CI检查，超标就阻断合并。

为什么用预算而不是目标？因为预算是硬约束，目标是软期望。人都是会妥协的，只有硬约束才能守住底线。具体落地可以用bundlesize或size-limit工具，在CI里对构建产物做体积校验。

6.2 监控体系的分层设计

前端监控通常分三层：错误监控（JS报错、资源加载失败、接口异常）、性能监控（加载性能、交互性能、资源性能）、行为监控（页面访问、关键操作路径）。三层的数据要能关联，比如一个报错发生时，能查到当时的页面路径、用户操作、性能数据。

错误监控的关键是去重和聚合。同一个错误在1000个用户那里发生，不应该产生1000条告警。按错误信息、堆栈、页面路径做指纹聚合，只对新增错误或突增错误告警。另外，sourcemap要上传到监控平台，否则堆栈全是压缩后的代码，没法定位。

性能监控的关键是采样和分位数。全量采集数据量太大，按比例采样即可。看指标不要只看平均值，平均值会掩盖长尾问题，要看P75、P95分位数。一个页面平均加载1秒，但P95是8秒，说明有相当一部分用户体验极差。

6.3 从监控数据反推架构问题

监控数据最大的价值不是“知道出事了”，而是“知道架构哪里有问题”。举几个我实际遇到的例子：

某个页面接口请求数异常多，查下来是组件层级过深导致重复请求，这是状态管理设计问题。某个chunk体积持续增长，查下来是公共组件被错误地打进了多个chunk，这是构建分割策略问题。某个错误只在特定机型出现，查下来是用了未polyfill的新API，这是构建目标配置问题。

监控是架构的反馈回路。没有监控，架构就是闭门造车；有了监控，架构才能持续演进。所以我在任何项目里都会把监控接入作为架构搭建的一部分，而不是等出事了再补。

6.4 性能优化的优先级排序

最后说下优化顺序，避免把精力花在收益低的地方。按投入产出比排序：

1. 减少首屏JS体积：收益最大，手段是代码分割、Tree-shaking、依赖替换。
2. 接口优化：合并请求、缓存、预加载，收益直接。
3. 资源加载优化：图片压缩、字体子集化、CDN，收益稳定。
4. 渲染优化：虚拟列表、懒渲染、防抖节流，针对长列表和复杂交互。
5. 缓存策略：HTTP缓存、Service Worker，收益大但复杂度高，放后面。

不要一上来就搞Service Worker或者极致的手写优化，先把前三条做扎实，性能就能超过大多数项目。

7. 我在架构落地中的几点真实体会

架构这件事，纸上谈兵容易，落地最难的是让人接受约束。我推分层规范的时候，被质疑过“太麻烦”；推构建体积检查的时候，被抱怨过“卡流程”。但坚持三个月后，当初反对最凶的人成了最积极的维护者，因为他们真切感受到了“改代码不再提心吊胆”的好处。

另一个体会是：架构文档要短，规则要能自动执行。写几十页架构文档没人看，但把规则写进ESLint、写进CI，每个人都会遵守。文档只解释“为什么”，工具负责“必须这样做”。

还有一点，架构不是一次设计完就固定的。业务在变，团队在变，架构也得跟着调。我一般每季度做一次架构复盘，看看哪些约束已经过时、哪些新问题需要新规则。架构的生命力在于演进，不在于完美。

如果你现在正准备搭一个新项目，我的建议是：先把分层和构建这两块做扎实，状态管理和监控跟上，微前端这类重武器留到真正需要时再上。架构的目标是让团队跑得快且不摔跤，不是让架构图好看。