企业官网建设流程全解析

前端开发干久了，大概率都经历过这种场景：一个页面里堆了几百行script，全局变量满天飞，改一个功能要顺着调用链翻半天，最后发现动一处崩三处。这种代码，圈内有个很形象的名字——面条代码。它不是说代码写得丑，而是说代码逻辑像煮烂的面条一样，缠在一起扯不开。随着项目越做越大，这种写法带来的维护成本会呈指数上升，于是就有了“前端模块化开发”这件事。

这篇内容不是什么学院派理论，而是我这些年实际改项目、重构代码沉淀下来的经验总结。围绕的核心就一件事：怎么把一团乱麻的面条代码，梳理成结构清晰、边界明确、能长期维护的结构化代码。里面会讲到模块化演进背后的逻辑、拆分的具体思路、实操重构的完整过程，以及那些不踩一次永远不会知道的坑。不管你是刚入门的前端新手，还是被历史项目折磨的中级开发者，这篇内容应该都能给你一些启发。

1. 从“能跑就行”到“跑得明白”：为什么我们会写出面条代码

1.1 别骂当年的自己，面条代码是“自然生长”出来的

我见过很多开发者痛恨自己早期的代码，其实没必要。面条代码不是某个人蠢，而是前端项目从小到大的自然产物。早期我们写页面，需求就一个：在页面上展示数据、响应用户点击。那时候的前端没有什么工程化概念，一个HTML文件里内联一段script，再引入几个公共的JS文件，感觉完全够用。

但随着业务增长，功能叠加，代码开始“自然生长”：A页面的点击事件里需要调用B模块的数据，B模块又依赖C函数，C函数里又直接改了全局变量……这种依赖关系不是设计出来的，而是需求迭代过程中一层层“拱”出来的。等到哪天你需要复用某一个功能，发现自己根本抽不出来——因为它跟旁边十几处代码都黏在一起。

这是面条代码的典型特征：高耦合、低内聚、隐式依赖、全局面污染。用术语说就是，模块边界模糊，职责混乱，任何一块代码的改动都可能波及一片。

1.2 模块化解决的不是“排版问题”，是“协作和演化问题”

很多新手会误以为模块化就是把代码拆成几个文件，拆完就完事了。如果是这么简单，那CSS引用随便放几个文件也算模块化了。真正的模块化，核心解决的是三个深层问题：

第一是命名空间污染。早期前端代码里最容易出现window.data、window.utils这种全局变量，谁都能读、谁都能改。两个不同的功能模块如果用了同一个名字的变量，后加载的文件就会覆盖先加载的，排查到崩溃你也未必能发现。模块化通过局部作用域隔离，让变量只在模块内部可见，需要对外暴露才通过显式导出。

第二是依赖关系的显式化。面条代码的依赖是隐式的，你不知道这段代码执行时要依赖哪些前置条件。模块化之后，每个模块通过import/require声明自己的依赖，构建工具和阅读者都能清晰看到调用关系。这不仅是给人看的，更是给工具看的——有了显式依赖，构建工具才能做静态分析、tree-shaking、按需加载。

第三是并行协作的效率。多人开发同一个项目时，如果代码没有边界，张三改了工具函数可能导致李四的功能直接挂掉。模块化相当于给每个开发者在代码层面画了一条“责任线”，只要各自守好模块边界，并行开发的冲突概率会大幅降低。

1.3 模块化不是一步到位的：演进路线里藏着很多设计智慧

前端模块化的演进，本质上是一部“作用域和加载策略的斗争史”。从最原始的全局函数，到后来的IIFE（立即执行函数表达式）、AMD、CommonJS、UMD，再到今天成为标准的ES Module，每一步都是被当时的场景逼出来的。

看到没有？每一种方案都是在解决前一种方案的痛点。CommonJS的同步require在浏览器场景下行不通，因为浏览器加载文件是异步的；AMD用回调解决异步，但写起来丑到劝退；ES Module直接语言层面支持，并且支持静态分析，所以它成了最终的赢家。

现在做新项目，我建议直接统一用 ES Module，别再开历史的倒车。如果维护老项目用了require，也要逐步往import迁移。这样做不是因为“新的一定好”，而是因为整个前端工具链——Vite、Rollup、Webpack——都是围绕 ES Module 优化的，你能白捡很多静态分析带来的性能红利。

2. 拆分不是拍脑袋：模块划分的原则和实操思路

2.1 先划单模块的高内聚低耦合：从“职责”而不是“文件”出发

很多初学者踩过这样的坑：模块化就是把原来的一个大JS文件按长度砍成几段，每个文件装几行代码。结果拆完发现，文件数量翻倍了，代码照样改不动。问题在哪？因为你还是在“切文件”，不是在“划模块”。

我自己的经验是：先识别职责，再确定文件边界。什么叫识别职责？就是看这段代码到底是干嘛的——是发请求的、是处理时间的、是渲染表格的，还是管理状态的？同一个职责的代码聚在一起，不同职责之间通过接口通信。一个经典的例子：工具函数formatDate不应该和商品列表的渲染逻辑放在同一个模块里，因为前者的职责是“把日期转成字符串”，后者的职责是“把数据变成用户看得懂的界面”。

模块内部还要做到“高内聚”：模块里的各个部分尽量都服务于同一个目标。比如一个userApi.js模块，里面所有函数都是跟用户相关的接口请求，这就算内聚；如果你往里塞了一个getProductList，那就破坏了内聚，因为别人需要“产品列表”的时候不得不依赖一个不是自己职责范围的模块。

2.2 边界到底怎么划：按业务域拆，还是按技术类型拆？

这是我被问得最多的一个问题。项目结构是views / components / utils / api这种按功能竖切，还是features / user / order这种按业务域横切？两种都有道理，但我建议新项目优先按业务域拆，理由很简单：业务的变化比技术类型的变化更频繁。

举个例子，用传统的views/components/utils分层结构，当你做一个“用户列表页”时，可能要同时改views/userList.vue、components/UserTable.vue、utils/userFilter.js、api/user.js四个地方。如果哪天这个业务域被整体砍掉了，你得从四个目录下去找相关文件删除。

而按业务域拆分——比如src/features/user/目录下面放components/、api/、hooks/、pages/——这个业务域的所有代码都集中在一个目录里。新增一个用户相关功能，你只需要改这个目录；要下线一个业务，直接删这个目录。对长期维护来讲，这种组织的成本低很多。

当然，跨业务公用的东西还是要独立出来，放到src/shared/或者src/common/里，比如通用的请求封装、通用的基础组件、通用样式变量。这里的判断依据是：复用程度。只有被三个以上业务域用到的代码，才值得下沉为公共模块。

2.3 拆分的粒度：拆到什么时候算够？

模块化也不是拆得越细越好。如果每个函数一个文件，那项目里的文件数量会爆炸，反而增加导航和理解成本。我自己总结了一个简单的粒度判断标准：

• 一眼看不懂这个文件是干嘛的？说明粒度太大，需要拆。
• 为了一行代码去建一个新的模块文件？说明粒度太小，需要并。
• 一个文件包含了多个互不相关的职责？说明边界划错了，需要重划。
• 改动一个功能要同时动三个以上的模块？说明接口设计有问题，需要收敛。

另外，我特别推荐以“读代码的体验”作为衡量标准。找同事来看你拆完的文件，如果他能在一分钟内说出每个文件大概管什么，并且能快速定位到他关心的功能在哪个文件里，那模块划分就是成功的。做不到的话，不管结构图上画得多漂亮，都要重新调。

3. 实地重构：把一个面条代码页面改造为模块化结构

光说不练没用，我拿一个实际的例子演示整个重构过程。场景是一个经典的管理后台“商品列表页”，功能包括：加载商品数据、表格展示、搜索筛选、加入购物车、记录日志。很多老项目里，这些代码全写在一个JS文件里，大概长这样：

3.1 重构前：感受一下什么是真正的面条代码

// 所有逻辑堆在一个文件里 var productList = []; var currentPage = 1; var pageSize = 10; var totalCount = 0; function loadProducts() { fetch('/api/products?page=' + currentPage + '&size=' + pageSize) .then(function(res) { return res.json(); }) .then(function(data) { productList = data.list; totalCount = data.total; renderTable(); updatePagination(); }); } function renderTable() { var rows = ''; for (var i = 0; i < productList.length; i++) { var p = productList[i]; rows += '<tr><td>' + p.name + '</td><td>' + p.price + '</td><td><button onclick="addToCart(' + p.id + ')">加入购物车</button></td></tr>'; } document.getElementById('productTableBody').innerHTML = rows; } function search(keyword) { currentPage = 1; fetch('/api/products?keyword=' + keyword + '&page=1&size=' + pageSize) .then(function(res) { return res.json(); }) .then(function(data) { productList = data.list; totalCount = data.total; renderTable(); updatePagination(); }); } function addToCart(productId) { fetch('/api/cart/add', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ productId: productId }) }).then(function() { console.log('add to cart:' + productId); updateCartCount(); }); } // ...后面还有更新分页、更新购物车数量等一堆函数

这个文件的典型问题很明显：第一，productList、currentPage、totalCount全部是全局变量，任何其他脚本都可以篡改；第二，loadProducts、search里面都各自发请求、各自处理渲染，代码重复度高；第三，renderTable里直接拼HTML字符串，将来要换框架、换渲染方式，这个函数基本要推翻重来；第四，这个文件只能用在当前页面，完全无法复用。

3.2 第一刀：从“函数抽取”开始，先让人看懂代码

重构的第一步我通常不是急着建目录，而是先把重复的逻辑抽成独立函数。上面这段代码里，请求和渲染的逻辑混在一起，先把它拆开：请求只负责拿数据，渲染只负责展示数据。

// api/product.js export async function fetchProducts(params) { const query = new URLSearchParams(params).toString(); const res = await fetch(`/api/products?${query}`); if (!res.ok) throw new Error('请求失败'); return res.json(); } // utils/render.js export function renderProductTable(container, products) { const rows = products.map(p => { const row = document.createElement('tr'); const tdName = document.createElement('td'); tdName.textContent = p.name; const tdPrice = document.createElement('td'); tdPrice.textContent = p.price; // ...构建按钮和绑定事件 row.append(tdName, tdPrice); return row; }); container.replaceChildren(...rows); }

这一步“不改变任何外部行为”，只是把逻辑从“纠缠在一起”变得“各归其位”。每次做这种重构，我会反复跑一遍功能测试，确认页面行为和重构前完全一致。不要试图一步到位，把重构风险控制在可回滚的范围内。

3.3 第二刀：引入状态管理，消灭“隐式全局变量”

面条代码的另一个罪状就是状态散落。productList、currentPage这些状态在全局定义，处处可改，出了Bug很难排查。我的做法是：把状态收拢到一个模块内部，通过明确的函数来修改。

在Vue 3项目里，我通常用reactive或者ref来管理页面状态，并且把修改状态的逻辑全部收敛到 store 或 composable 里。这样组件只读数据、触发动作，不直接改状态。

// stores/productStore.js import { reactive } from 'vue'; import { fetchProducts } from '@/api/product'; export const useProductStore = () => { const state = reactive({ list: [], currentPage: 1, pageSize: 10, total: 0, keyword: '' }); async function loadProducts() { const data = await fetchProducts({ page: state.currentPage, size: state.pageSize, keyword: state.keyword }); state.list = data.list; state.total = data.total; } function setKeyword(keyword) { state.keyword = keyword; state.currentPage = 1; loadProducts(); } return { state, loadProducts, setKeyword }; };

看到没有？任何对状态的改动都必须经过loadProducts/setKeyword这些方法。如果将来出现状态被意外改掉的情况，你只需要排查这几个入口即可，不用满代码去找productList = xxx。

3.4 第三刀：页面组件化，渲染和交互一起封装

逻辑处理拆完了，下一步是界面部分。传统的字符串拼接HTML有两个问题：一是转义难做，容易有XSS风险；二是交互逻辑和渲染全混在一起。用组件化之后，每个界面块都变成一个黑盒，暴露props和events作为接口。

以Vue 3 + Element Plus为例，商品表格可以封装成一个组件：

<!-- components/ProductTable.vue --> <template> <el-table :data="products"> <el-table-column prop="name" label="商品名称" /> <el-table-column prop="price" label="价格" /> <el-table-column label="操作"> <template #default="{ row }"> <el-button @click="handleAdd(row)">加入购物车</el-button> </template> </el-table-column> </el-table> </template> <script setup> const props = defineProps({ products: { type: Array, default: () => [] } }); const emit = defineEmits(['add']); function handleAdd(row) { emit('add', row); } </script>

然后在页面里使用这个组件，页面本身只负责组合这些组件，不再关心表格的渲染细节。这种“拆组件”的思路，其实跟3.2里拆函数是一脉相承的：找出职责边界，用接口连接，而不是让代码直接彼此调用。

组件化改造完成后，你会看到一个明显的变化：原来改一个功能要担心影响其他功能，现在每个组件有明确的输入输出，只要接口不变，内部随便改都不会波及外部。这其实就是模块化给代码带来的“安全感”。

3.5 第四刀：统一模块出口，把“找到模块”变成“依赖模块”

项目大了以后，另一个隐性成本是“找文件”。我从@/features/product目录访问时，不希望记住每个文件的具体路径。解决办法是：在每个业务域目录下放一个index.ts统一导出，外部只依赖这个目录入口。

// features/product/index.ts export { default as ProductTable } from './components/ProductTable.vue'; export { default as ProductFilter } from './components/ProductFilter.vue'; export { useProductStore } from './store/productStore'; export { fetchProducts } from './api/product';

这样做的好处是，调用方只需要import { ProductTable } from '@/features/product'，不用关心内部结构。将来你重构目录结构、调整文件位置，外部引用完全不用改。这带来的是“模块内部自由变化”的底气。

4. 模块化之后的新问题：常见报错与排查技巧

模块化不是银弹。代码拆分以后，新的问题也会冒出来——而且这些坑，你不踩一次根本不会长记性。

4.1 循环依赖：最经典的模块化陷阱

循环依赖长什么样？a.js里import了b.js，而b.js里又import了a.js。在小型项目里这个问题不算致命，但一旦模块化拆分得细，循环依赖就特别容易发生。

举个例子，购物车模块需要知道用户是否登录，于是cart.js引用了user.js；而用户信息模块在登录成功后需要同步购物车状态，于是user.js又引用了cart.js。两个模块互相引用，运行时就会出现“Cannot access before initialization”之类的问题。

排查方法：第一，尽量避免跨业务域的引用，公共状态提升；第二，如果循环依赖必须存在，把公共依赖抽到第三方的模块，让两个模块都去依赖第三方，而不是互相依赖；第三，检查依赖图的工具，比如madge，可以快速输出模块依赖关系图，一眼定位循环链路。

4.2 全局变量残留：模块化改造后依然被坑

有些老项目做了模块化，但历史遗留的window.xxx还在。这种情况在改造合并阶段特别常见：你拆了一个模块，但某些旧代码还是通过window.config读取配置。结果新模块里改了配置，旧代码读到的还是旧值。

我的建议是：模块化改造过程中，把全局变量全部消灭在“唯一入口”。也就是说，旧代码不再自己直接挂window，而是统一从一个配置模块里import。如果涉及第三方库依赖全局变量（比如某些插件必须window.foo），也要在一开始做好兼容层，而不是让业务代码顺手挂。

4.3 依赖地狱：模块化以后，忘了锁版本

很多项目模块化之后，按业务域拆成了几十个包，依赖关系复杂了。这时候如果不用锁文件（package-lock.json/pnpm-lock.yaml），过几天Node_modules重装，版本轻微浮动都可能导致模块间接口不兼容，然后报出一堆“is not a function”之类的错误。

机制上有一个概念叫语义化版本（SemVer）：^1.2.3允许安装1.x.x的最新版。看起来没问题，但偏偏有些库会在 minor 版本里引入破坏性变更。所以，项目里不仅要用锁文件，还要在CI流程里跑一遍npm ci而不是npm install，确保构建环境里的依赖版本永远和开发环境一致。

4.4 面试和日常都会被问到的模块化高频问题

既然热搜词里有“前端面试题”，那就顺带聊聊模块化部分的高频考点。面试官问模块化，表面上是考你语法，实际上考的是你有没有真正理解“模块化是为了解决什么问题”。

完全答好这些问题，光背“八股”是不够的，你得真在项目里遇到循环依赖、真去配置过 tree-shaking、真排查过模块缓存导致的 Bug。所以别只背面试题，把模块化落实到你正在写的前端项目里，比什么都管用。

5. 再往前走一步：工程化时代下的模块化扩展

模块化解决了代码组织问题，但当项目规模继续膨胀，模块化还会往更宏观的方向演化。这里简单提几个我在实际项目中用到的方向，如果你正卡在“模块化之后下一步干什么”的阶段，可以参考。

组件库与设计系统：如果你的公司有多个项目，会发现不同项目都用各自维护的按钮、弹窗、表单，代码重复率极高。这时候就应该抽一个内部通用组件库，甚至做成 npm 私有包，跨项目共享。这里要注意的不是“组件怎么写”，而是“接口怎么设计”——组件库的 API 一旦暴露给多个项目，改起来牵一发动全身，所以必须定义清楚版本和变更策略。Element Plus 这类开源库是怎么做兼容的，可以好好学一学。

大文件上传里的模块化拆分：比如热搜里提到的“使用 worker 上传大文件”。大文件切分、MD5 计算、并发上传、进度回调、失败重试，这些逻辑如果写在一个文件里，照样会变成面条代码。正确做法是每个环节一个模块，worker 负责计算 hash，业务层负责调度，状态管理负责维护上传进度。你会发现，模块化的本质逻辑在这里依然成立：用清晰的边界隔离复杂度。

微前端（qiankun）：当公司里有多个团队维护一个大型系统，或者若干老系统要整合成门户，微前端就上场了。它本质上是一种“应用级别的模块化”：每个子应用独立开发、独立部署，主应用负责统一加载和通信。qiankun 的实现里有很多模块化的智慧，比如沙箱隔离JS作用域、样式隔离、应用间通信协议。但要注意，微前端不是万能的，项目不大就别硬上，它的运维成本和通信成本不是新手能轻松驾驭的。

我自己的体会是，前端的模块化之路没有终点。今天你可能拆好了组件，明天就要面对跨项目共享，后天可能还要做跨团队协作。但只要你始终把握住那个核心——把大问题拆成小问题，让每个小问题有清晰的边界，通过接口而不是隐式依赖来协作——无论前端技术怎么迭代，你都能游刃有余。

最后补一个我自己的实战习惯：重构模块化代码时，每拆完一个模块就提交一次代码，提交信息写清楚“拆了什么、为什么拆、行为有无变化”。别怕提交太多，结构化拆分的每一步都值得留痕。这种习惯救过我至少三次——有一次拆到一半方向走偏了，直接git revert回到上一个干净状态，整个晚上不用对着跑不起来的代码发愁。