接手过几个 Vue 项目的重构之后我越来越觉得多模块这件事被大家理解得太窄了。很多人一说模块化第一反应就是拆几个组件、抽几个工具函数顶多再把路由拆成子路由但项目一旦真正复杂起来——比如同时存在商品、订单、用户、营销、售后等五六条业务线——这种浅层拆分很快就绷不住了。今天这篇就围绕vue如何构造多模块的程序这个话题把我自己踩过的坑、最终沉淀下来的组织结构、路由拆分、状态管理划分、API 收敛方式以及构建层面的配合一次性说清楚。这篇文章适合谁我觉得至少有两类人值得看一类是项目已经长到几万行代码、想在失控前做一次模块化改造的开发者另一类是刚进团队、需要接手一个按模块组织的大型 Vue 项目、想知道为什么目录长这样的新人。我会尽量把每个设计决策背后的原因也讲出来而不是只丢一个目录结构让你照抄。1. 多模块到底解决什么问题先认清单模块项目的失控过程先从一个很典型的场景说起。我早年间维护过一个后台管理系统刚起步的时候特别爽一个views目录下面按页面平铺router/index.js里几百行路由一眼望到头store里放一个巨大的 Vuex 模块管理所有状态。开发效率很高每天能交付好几个页面。但到了第二年底这个项目开始明显不对劲。具体的失控症状是这样的views目录下三四十个.vue文件平铺在一起命名上有user-list、order-list、goods-list你根本分不清哪些页面属于同一条业务线router/index.js接近两千行新增一个页面要滚动半天找到插入位置store/modules里的模块虽然拆开了但模块之间互相引用 state 的情况越来越多改一个模块动不动要连带测试三个模块最要命的是A 业务线的组件为了图方便直接 import B 业务线某个页面里的子组件后来 B 业务线一重构A 这边莫名其妙挂了。这种状态就是典型的物理拆分、逻辑没有拆分。目录上看起来是模块化的但代码之间的依赖关系是混乱的模块边界形同虚设。那什么才是真正的多模块我个人对它的定义是按照业务域把路由、状态、接口请求、页面组件封装成一个相对独立的功能域域与域之间通过明确的约定通信而不是随意的函数调用和 import 关系。它不是要消灭跨模块协作而是要让这种协作变得有限、可控。这里还要澄清一个容易混淆的概念。很多教程里说多模块指的是多页面应用MPA每个页面一套 HTML。但对大多数管理后台或者中后台系统来说我们实际遇到的是 SPA 内部的多模块架构——整个应用还是单页的只是代码组织上按业务域拆分。这两种多模块是完全不同的东西后者才是日常开发中真正高频遇到的场景。我在重构之前先把目标拆成了四条硬性指标之后所有的决策都以这四条为评判标准业务域边界清晰比如订单模块的代码不能散落在用户模块和商品模块里路由配置可插拔加一个模块不用改动已有模块的代码状态管理不越界模块的 store 只操作自己的状态构建产物可优化能够针对模块做代码分割而不是全量打包。这四条里前两条属于组织规范后两条属于技术保障。缺任何一条多模块架构都只是空中楼阁。2. 路由拆分与目录结构让模块从“看得见的层面”先立起来多模块改造的第一步永远是目录结构和路由。不是因为它们简单而是因为目录是团队协作时大家看得见、摸得着的共同语言。我在重构后的项目里用的是下面这套结构后端管理场景可以直接照搬src/ ├── api/ # 接口请求统一入口 │ ├── request.js # axios 实例与拦截器 │ ├── user.js │ ├── order.js │ └── goods.js ├── assets/ ├── components/ # 跨模块共享的基础组件 │ ├── BaseTable.vue │ ├── BaseDialog.vue │ └── BaseForm.vue ├── layouts/ │ ├── AdminLayout.vue │ └── BlankLayout.vue ├── router/ │ ├── index.js # 路由汇总 │ └── modules/ │ ├── user.js │ ├── order.js │ ├── goods.js │ └── marketing.js ├── store/ │ ├── index.js │ └── modules/ │ ├── user.js │ ├── order.js │ └── goods.js ├── views/ │ ├── user/ │ ├── order/ │ ├── goods/ │ └── marketing/ └── main.js看到这个结构很多人第一反应是这不就是常见的分层结构吗没错但它和伪模块化的关键差别在于views下的目录和router/modules、store/modules、api下对应的文件是严格一一对应的。也就是说接到一个用户模块的需求你能从api/user.js、store/modules/user.js、router/modules/user.js、views/user/四个地方把相关代码一次找齐。这样做之后找一个页面的代码根本不需要全局搜那种“页面跳转不知道跳哪”、“改样式找不到组件”的情况在早先那个项目里很常见现在因为每个业务域的归属是明确的定位耗时起码省了一半。路由这边是拆分的关键。我建议不要把所有路由写在router/index.js里而是每个模块维护自己的routes数组然后汇总到入口文件类似于这样// router/modules/order.js export default { path: /order, component: () import(/layouts/AdminLayout.vue), children: [ { path: list, name: OrderList, component: () import(/views/order/List.vue), meta: { title: 订单列表, permission: order:list } }, { path: detail/:id, name: OrderDetail, component: () import(/views/order/Detail.vue), meta: { title: 订单详情, hidden: true } } ] }// router/index.js import orderRoutes from ./modules/order import userRoutes from ./modules/user import goodsRoutes from ./modules/goods const routes [ { path: /, redirect: /dashboard }, ...orderRoutes, ...userRoutes, ...goodsRoutes ]注意几个细节。第一模块路由统一挂到AdminLayout.vue下作为 children这样所有页面天然共享同一套侧边栏和顶栏不需要每个模块各自引入 Layout。第二路由级组件用动态 import这是代码分割的基础后面构建优化章节会细说。第三name字段必须全局唯一我之前就吃过亏——两个模块里都写了name: List导致跳转时永远跳到第一个匹配的路由排查了很久才发现是命名冲突。模块路由的懒加载写法在 Vue Router 4.x 里有些细微差别。早期版本推荐() import(/views/order/List.vue)但在 Vue Router 4 里可以给动态导入的组件命名便于配合KeepAlive// Vue Router 4 中建议写法 component: () import(/views/order/List.vue), // 如果需要配合 KeepAlive 做缓存 component: () ({ component: import(/views/order/List.vue) })当然这个不是必须的但如果你用到 KeepAlive 的include属性最好定期检查一下导入组件的 name 是否和路由 name 保持一致否则缓存不生效切回列表页会丢失筛选条件。这套目录和路由方案的好处是新增一个模块的代价被降到了极低。只需要在views下建目录、在api下加文件、在store/modules下加文件、在router/modules下加文件然后router/index.js里注册一下就行。已有的模块完全不用动团队并行开发时基本不会产生代码冲突。3. 状态管理的模块化边界Pinia 拆分、store 间通信与几个我踩过的坑目录和路由解决的是页面从哪来状态管理解决的是数据放哪里。在这个问题上我经历过从一个 Vuex 大 store到模块 store 严密封装的完整过程心得比较深。先给结论如果在 Vue 3 项目里状态管理直接用 Pinia别用 Vuex。原因不只是 Pinia 是官方推荐的新方案更核心的是它天然就是模块化的——每个 store 独立成文件没有像 Vuex 那样的全局store对象反复在其中注册模块的动作心智负担小很多。在 Pinia 里一个业务模块的 store 长这样// store/modules/order.js import { defineStore } from pinia import { getOrderList, getOrderDetail } from /api/order export const useOrderStore defineStore(order, { state: () ({ orderList: [], total: 0, loading: false, currentPage: 1, pageSize: 10 }), getters: { paidOrders: (state) state.orderList.filter((item) item.status paid) }, actions: { async fetchOrderList(params) { this.loading true try { const { list, total } await getOrderList(params) this.orderList list this.total total } finally { this.loading false } } } })我观察到很多团队的 store 拆了个问题只是把 state 按模块拆了但 actions 里做的事情五花八门——有直接改其他模块 state 的有在 store 里处理视图逻辑的还有在组件里把 API 请求结果暂存在组件data里而不进 store 的。这些都是边界不清的表现。我在团队里定的规矩是业务数据必须进 store视图临时状态留在组件里API 请求必须在 store 的 action 里发组件不直接调 api 层。为什么这么定因为当多个页面都依赖同一份数据时比如列表页和详情页都要显示订单状态如果把数据存在组件里要么重复请求要么通过 event bus 传播都是后期维护的炸弹。统一走 store数据唯一来源明确刷新时机可控跨模块需要共享数据时也能有明确的出口。那 Pinia 模块间通信怎么做一个常见的场景是用户下单成功后订单模块需要把用户的累计消费额更新到用户模块的 store 里。Pinia 的写法是直接跨 store 调用不需要任何事件机制// store/modules/order.js import { useUserStore } from ./user export const useOrderStore defineStore(order, { actions: { async createOrder(payload) { const result await createOrderApi(payload) // 调其他模块的 action const userStore useUserStore() userStore.updateTotalSpent(result.amount) return result } } })注意这里能这么写有一个前提useUserStore() 必须在函数内部调用不能在 store 文件顶层调用。原因在于 Pinia 依赖当前的活跃 pinia 实例如果在文件顶层就把 userStore 实例化在 SSR 或某些测试场景下会报 getActivePinia() was called but there was no active Pinia 的错。这个属于写 Pinia 必踩的经典坑写成函数内调用就稳了。不过跨 store 调用也要控制频率和方向。我在代码 review 时见过一种很典型的环形依赖user store 调 order storeorder store 又调 user store。这种状态说明两个模块的职责划分本身有问题频繁互相调用的地方往往意味着这些状态应该被提升到一个共享层。我在实践中用的判断标准很简单如果两个 store 之间互相调用的次数超过 2 处我就停下来重新审视一次模块边界看看是不是把某些公共状态放到了错误的位置。在 store 划分上还有一个经验不要为了看起来模块化而把原子状态拆得过于琐碎。比如用户 token、用户基本信息、权限列表这三样东西虽然分属不同语义但在绝大多数系统里它们是同生共死的维护在一个userstore 里操作起来更顺手。为了拆而拆只会让跨 store 通信的代码数量爆炸反而违背了模块化的初衷。Vuex 老项目的情况我也遇到过。如果代码还在 Vuex 上模块化的核心手段就是 Vuex Module namespaced: true。加了 namespaced 之后dispatch 和 getters 都要带模块前缀比如dispatch(order/fetchList)这在跨模块调用时特别啰嗦。如果你的项目还有余力我建议把 Vuex 直接迁移到 Pinia因为 Pinia 的 store 之间是平级关系没有嵌套路径长期维护更省心。4. API 请求层按模块收敛axios 封装、接口文档对齐与接口文件只做一件事很多项目的模块化做到上面两步目录和 store就停了但我认为 API 层才是真正决定模块能否独立演进的命门。一个业务模块如果所有接口请求都分散在组件里或者集中在一个巨大的api/index.js里那模块边界依然是不完整的。说实话把 API 按模块拆成文件是最容易抄的作业但真正难的是让整个团队遵守接口文件只做一件事的原则。我见过有人把api/order.js写出了 600 行里面塞了订单、支付、退款、物流、售后五个域的接口理由是这些都是订单相关。这种为了省事的合并等到退款和物流各自要做二期迭代时就只能在一个文件里互相拉扯。仔细想想看为什么会这样因为大家对模块的粒度认识并不一样。我比较推崇的粒度是前后端接口文档里的领域划分就是前端 API 文件划分的依据。后端如果给了order、refund、logistics三个 controller 或领域模块前端就对应api/order.js、api/refund.js、api/logistics.js一一对上。这样前后端联调时找接口的心理成本最低后端接口变动时影响面也清晰。不要试图用文件数量去做文章文件粒度对不上领域模型后面必然返工。真正要花心思的是request.js这个 axios 实例的封装。好的封装应该做到业务代码永远只关心数据不管 HTTP 状态码、token 刷新、断网提示这类杂事。我通常在项目里做一个比较标准的封装拆成三个层级// api/request.js import axios from axios import { ElMessage } from element-plus import { useUserStore } from /store/modules/user const service axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 15000 }) // 请求拦截器携带 token service.interceptors.request.use( (config) { const userStore useUserStore() if (userStore.token) { config.headers.Authorization Bearer ${userStore.token} } return config }, (error) Promise.reject(error) ) // 响应拦截器统一处理业务码 service.interceptors.response.use( (response) { const res response.data // 约定格式{ code: 200, data: {...}, message: ok } if (res.code ! 200) { ElMessage.error(res.message || 请求错误) // 某些业务码需要特殊处理比如 401 跳登录 if (res.code 401) { const userStore useUserStore() userStore.logout() window.location.href /login } return Promise.reject(new Error(res.message)) } return res.data }, (error) { // 网络错误 / 超时 ElMessage.error(error.message || 网络异常) return Promise.reject(error) } ) export default service有了这个封装每个模块的 API 文件就可以很干净地做接口描述这一件事// api/order.js import request from ./request export const getOrderList (params) request.get(/order/list, { params }) export const getOrderDetail (id) request.get(/order/detail/${id}) export const createOrder (data) request.post(/order/create, data) export const updateOrderStatus (id, status) request.patch(/order/${id}/status, { status })我特别想在 API 文件的命名规范上多说两句。方法名的定义我通常遵循动词 业务名的格式比如getOrderList、createOrder、updateOrderStatus。这样做的原因是在 store 的 actions 里调用时代码读起来像是一句自然语言const list await getOrderList(params)任何人不用看 API 文件也知道这个接口是干嘛的。不要起fetchData、saveInfo、getDetail这类模糊名字一个项目里多几个这种名字后期就全靠猜了。另外我一直坚持 API 文件里不做数据转换。比如后端返回的字段是goods_name前端组件里要用goodsName这个转换放在哪里我的答案是放在 store 的 action 里或者组件内API 文件保持参数原样传、返回原样给。这样做的好处是接口对接时如果有字段调整只需要改 API 文件一处但如果有展示层的数据加工改了 API 文件会影响所有使用方边界就乱了。数据请求这块还有一个容易被忽略的模块化考量在 store 的 action 里调用 API 的统一出口必须是模块自己的 api 文件。不要让 order 的 action 去直接调用api/user.js里的接口。如果确实需要用户信息应该通过读取userStore的已有数据来获取。这样每个模块对外暴露的能力边界才清晰后端接口有变动时波及面也最小。5. 组件按职能分层基础组件、业务组件、页面组件不能混在一个锅里多模块如果只做到路由、状态、API 三个层面的拆分代码组织已经比较清晰了但组件层往往是最后一个失守的阵地。因为在业务迭代中大家最常写的代码就是组件最急的时候谁还顾得上边界先跑通再说。于是组件目录往往最先变成垃圾堆。我在重构后把组件分成了三层并且在目录上做了强制隔离第一层是基础组件src/components不包含任何业务语义比如封装后的按钮、弹窗、表格、表单、上传组件等。它们只接受 props 和 emit 事件不依赖任何 store也不调用任何 api。基础组件的设计目标是通用性任何模块都能用改它的样式时只影响展示层。第二层是业务组件src/views/order/components随具体业务模块走放在对应模块目录下。例如订单模块的StatusTag.vue、OrderAmountInput.vue它们可能读取useOrderStore()也可能调用该模块 api 文件里的方法。这类组件不应该出现在其他模块的代码里别人要用也应该复制一份到自己的模块目录下再改——这话看着不讲道理但实际能避免太多跨模块纠缠。第三层是页面组件src/views/order/List.vue一个路由对应一个页面组件页面组件像导演一样负责组织业务组件、调用 store 的 action、处理路由参数而不是把大段逻辑塞在模板里。我见过不少半吊子项目基础组件和业务组件全放在src/components下看起来好像没什么问题直到某个模块的人改了一个公共组件的默认值其他模块的页面 UI 悄悄变了。这就是分层不清带来的经典事故。为了让这三层在代码层面也有约束力我在项目里启用了两个工具不细讲但值得提一是在 ESLint 里检查no-restricted-imports限制页面组件只能 import 自己模块下的业务组件二是给组件文件加上统一的 name 前缀比如基础组件以Base开头业务组件以模块名开头OrderStatus、GoodsCard。这样做不是为了好看而是让代码 review 时扫一眼 import 语句就能看出依赖方向是否越界。组件层还有一个容易被人忽略的模块化细节组件之间不要互相 import 对方的私有组件。比如订单模块的StatusTag.vue被商品模块的GoodsList.vue引用了这种依赖在短期内很省事但长期一定会导致模块重构时牵一发动全身。正确的做法是要么把共享能力沉淀到第一层基础组件比如做成BaseStatusTag用 props 控制状态值对应的文案和颜色要么让商品模块自己实现。多花半小时复制一份比以后改一个组件时要通知三个模块的负责人要划算得多。组件通信层面我们在模块内部用 props emit 已经足够。跨层级传值的时候Vue 3 的组合式 API 提供了provide/inject很多情况下比逐层传 props 简便得多而且让组件树之间的数据流变得显式。比如订单详情页里有一个OrderDetail容器组件它向下分发了订单的基本信息、商品列表、操作日志三个子区域就可以用provide(orderDetailData, order)全局注入子组件直接inject(orderDetailData)读取。但注意依赖注入不要越用越上头。如果某个 store 的数据刚好和注入的内容一致——比如订单详情页的数据本来就存在useOrderStore()里那组件直接用 store 就行不必再多一道 provide 的复制。provide/inject 真正适合的场景是某个组件的局部状态需要被后代组件共享但又不值得放进全局 store。把握住这个边界组件通信不会乱。6. 多模块后的构建与联调升级按需加载、代码分割与微前端兜底模块化改造做到前五步代码组织的层面已经比较完备了但模块化如果没有构建层面的支撑打包出来的可能还是一个大 bundle首屏性能依然没有改善。Vite 下只要你在路由组件里使用了动态 importVite 和 Rollup 默认就会为每个动态导入生成独立的 chunk——也就是自动代码分割。所以严格来说路由懒加载写上之后代码分割这件事就已经自动完成了。不过多模块项目真正需要关注的是chunk 的组织策略。默认情况下Rollup 会把所有动态 import 的模块各自打成 chunk但有些模块之间有共享依赖比如多个模块都用了一个公共组件如果不做配置这个公共组件可能被重复打包进多个 chunk 里。Vite 里可以在build.rollupOptions.output.manualChunks里做手动分包。// vite.config.js export default { build: { rollupOptions: { output: { manualChunks: { vue: [vue, vue-router, pinia], ui: [element-plus, element-plus/icons-vue], echarts: [echarts] } } } } }这样配置后第三方库会被单独拆出来利用游览器的长缓存策略业务代码更新时不会让用户重新下载整个依赖包。结合路由懒加载后用户访问订单模块时只加载订单相关 chunk 和公共 chunk首屏加载时间一般能减掉挺多。如果是 webpack 老项目对应的配置项是optimization.splitChunks。这里我忍不住想吐槽一句老项目里用import()动态加载时路由懒加载经常会因为cacheGroup配置不对导致一个 chunk 异常巨大。排查思路是先看 webpack-bundle-analyzer 的产物报告确认大 chunk 里装的是什么再决定是把公共依赖抽出还是把某个模块手动拆分。不要凭空调参数一定要先有报告再做针对性调整。说完构建再展开一下微前端。有人说都做多模块了是不是直接用微前端彻底拆成多个应用更好我的态度是微前端是兜底手段不是默认方案。单页应用内部的多模块架构已经能把大部分业务系统的复杂度控制住。只有当出现下面这些信号时我才建议往微前端方向走多团队开发各团队的技术栈不同一部分人用 Vue 2一部分人用 Vue 3甚至还有 React 的存量模块某个模块体积过大且更新频率极高希望它独立构建、独立部署、独立发布有存量老系统需要嵌入新系统却又没精力完全重写。如果决定上微前端目前国内最成熟的开源方案还是 qiankun。qiankun 的主应用和子应用可以都是 Vite Vue 3主应用负责路由分发和应用挂载子应用可以单独部署到独立的服务器或子路径。这里有个实操提示Vite 构建的子应用作为 qiankun 的子应用时必须开启base: ./或设置正确的子路径部署前缀否则子应用内部的资源请求会报 404。另外子应用的 Vite 配置里需要做一点点适配把build.target设置成esnext避免动态导入的微前端加载失败。这类问题在 qiankun 官方文档的 Vite 分支有详细说明实际踩过坑的人都知道微前端本身并不难难的是各种构建配置组合起来后出现的边缘问题。还有一点容易被忽略但影响开发体验很大的是代理配置。多模块项目在开发环境联调时常常需要对接不同的后端服务。比如订单模块对接订单服务用户模块对接用户服务如果项目里只有一个全局的VITE_API_BASE_URL开发时切换环境就非常痛苦。我在项目里通常给每个模块留一个可覆盖的环境变量VITE_API_BASE_URL/api VITE_API_USER_URL/user-api VITE_API_ORDER_URL/order-api然后每个 api 文件根据自己的模块用不同的 baseURL 创建一个 axios 实例// api/order.js import axios from axios const orderRequest axios.create({ baseURL: import.meta.env.VITE_API_ORDER_URL, timeout: 15000 })vite.config.js里对应做好多个代理目标server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true }, /order-api: { target: http://localhost:8082, changeOrigin: true }, /user-api: { target: http://localhost:8081, changeOrigin: true } } }这种多代理配置对团队开发非常友好前端不用等后端把所有服务域名统一好再动工。当然如果你整个项目只有一个后端服务那就不需要这么处理保持单一 baseURL 即可。7. 从零开始落地一套多模块改造方案我建议的顺序与几条硬性约定很多读者看完上面的内容可能已经有了一个大致方向但真正动手改造时会发现问题不在于不会写代码而在于不知道从哪个文件开始改。我在上个项目里带团队做过一次完整的多模块化改造这里把实施顺序列出来顺序很重要能少走很多弯路。第一步先画业务域地图。把所有页面和接口列出来按业务域分好组。这一步不需要写任何代码纯粹做梳理。分组的结果直接决定后续目录怎么建要拉着前后端一起对齐避免后端当作订单域、前端当作支付域这种领域认知不一致的问题。第二步搭骨架。先建好router/modules、store/modules、api下的目录结构把第一个模块建议选业务逻辑最简单的一个完整地落进去作为全团队的样例。样例特别重要因为抽象的规范很难传达但一份完整的代码样例能统一所有人的写法。第三步迁移路由。把原来集中在router/index.js里的路由逐步迁移到各模块文件里。迁移时同时把组件路径迁移到views/业务域/下。每迁一个模块就构建一次确保没有散落的/views/order这类硬编码路径遗漏。第四步迁移状态和 API。路由迁移完成后再动 store 和 api因为 store 和 api 的拆分布局较大且涉及组件内调用点改动晚一点做可以降低和路由迁移的耦合风险。第五步收尾检查。全局搜索api目录之外还有没有直接引用 axios 的文件、store目录之外有没有直接修改 state 的代码、views目录之间有没有跨模块的组件 import。这一步往往能揪出不少历史遗留。除了步骤之外我还想在末尾分享几条当时团队内部定的硬性约定。这些约定没有写在任何框架文档里都是实际项目沉淀出来的对长期维护意义很大业务组件不允许出现在src/components下。基础组件以Base前缀命名业务组件以自己的模块名作为前缀。代码 review 时凡是不符合前缀的 import 直接打回。store 的 action 是唯一允许调用 api 层的地方。组件里直接axios.get或者直接调 api 函数属于违反约定。任何跨模块的数据读取必须通过 store不能直接 import 对方模块内部的文件。新增一个业务域必须同时建好views/业务域、api/业务域.js、store/modules/业务域.js、router/modules/业务域.js四个文件不允许漏项。提交代码前跑一遍vue-tsc如果是 TS 项目和eslint从工具层面挡住大部分边界破坏者。这些约定一开始会让人觉得繁琐但坚持两三周后会变成肌肉记忆。有读者问我那项目管理成本不就上去了我的体会是前期多花的那一点点时间到后期找 bug、改需求时能十倍省回来。一个订单状态从待支付改成待确认的需求放在模块化清晰的项目里我只需要动一个 store 的一个 action、一个组件的几个状态值放在一锅粥的项目里我得全局搜好几次可能还漏改一处。这个对比就是模块化的全部意义。
