Nuxt大型单体应用痛点之目录结构篇

一、遇到的实际问题

年初，我对去年开发的《个人数据管理中台》项目开展了一系列代码优化工作，包括统一目录与文件的命名规则、完善服务端接口的 Typescript 类型推导、统一客户端 API 请求类的方法命名规则、对所有vue页面及组件进行Typescript改造等。

在执行上述代码优化的过程中，我逐渐遇到了一个问题：在调改应用模块的代码时，需要跨目录翻阅多个文件，带来了不小的心智负担。且随着项目模块增多、文件量大幅增长，这种负担越来越容易在修改时产生问题。

深究根源，核心问题在于Nuxt 3/4 的标准目录结构默认按技术类型分层：所有的前端代码都放在/app目录，所有的后端代码都放在/server。这种结构对小型项目而言清晰易懂，但对于包含多个业务模块的管理中台，会引发严重的上下文切换疲劳 ——例如为了开发一个“用户管理”功能，我需要在不同目录的文件树之间来回跳跃。

后续在 Github 的 Nuxt 目录 RFC 讨论贴中，我发现了基于领域驱动设计的目录结构思路，这与我以往的项目开发习惯类似：将同一模块下的不同类型文件聚合在专属的模块文件夹中，便于梳理模块的前后端对应逻辑。基于此，我开始探索在 Nuxt 4 中实现该设计的具体方式。

二、设想的解决方案

2.1 使用Layers实现领域分层

提到 Nuxt 4 的 Layers（层），大多数教程仅展示了 “配置 / UI 样式覆盖” 的用法，但其实它也是目前最优雅的物理分层方案，把每个模块视作一个层，拥有自己的一套composables、utils、server逻辑。主项目只需要通过 extends 配置，就可以像叠罗汉一样把它们叠起来。

这种方式有两大核心优势：

1. 原生支持：Nuxt Layers 的目录可实现自动导入，无需手动调用钩子注册；
2. 易扩展改造：层结构与单应用项目一致，后期可快速将各层分离为独立单应用，甚至可以迁移到微前端架构。

Nuxt 官方文档也明确提及，Layers 可用于实现领域驱动模式的架构设计。

2.2 使用Nuxt Modules封装模块功能

最初我与ChatGPT沟通时，它提出“使用Modules来封装模块功能”的想法，经过一些对话试验确实鼓捣出了一版最小Demo，可以在运行时把页面和接口注册到项目中。

ChatGPT给出的目录结构

注册路由和服务端API

但当我准备深入拓展的时候，却发现只要按下F5刷新页面就会出现404错误，后续ChatGPT调整了好多版注册插件，都没有解决这个问题，于是我只能先略过这个方案了。

2.3 通过IDE的Scope功能筛选文件树

借助 WebStorm 的 Scope、Favorites、File Colors 等功能，可以近似实现按模块聚合视图的效果。具体操作是通过「Settings」→「Appearance & Behavior」→「Scopes」→「Local Scope」创建自定义作用域。

操作步骤

随后在左侧目录树切换至该作用域，即可查看选定的模块文件夹结构。这在单独调改某一模块代码时能起到一定辅助作用，但在Debug需要翻阅公共文件时，自定义作用域会存在视图局限，实际上体验效果感觉不太行。

点击刚创建的作用域

可以看到选定的目录树结构

2.4 使用微前端聚合多个功能项目

还有一种方案是使用qiankun（乾坤微应用）、Module Federation（模块联邦）等方式，创建一个壳应用和多个子应用实现大项目的功能分拆。壳应用只负责导航和基础框架。不同的业务模块（如 ERP、CRM）作为独立的 Nuxt 项目开发，最后通过微前端框架的跨应用通信技术聚合在一起。

国内微前端技术用的也比较多了，经历过一定历史考验，团队多人协作采用这种方式确实可以提升一定开发效率。但作为个人项目，使用微前端分拆会极大提升项目复杂度，维护不同子模块（相比单体应用）也会耗费更多时间，不是很划得来。

微应用架构

2.5 方法总结

我用AI对上面几种方式进行了一个大致的优略势总结，在没有更好的方案前，我打算先使用Layers进行优化调整，这样后期即使要拆项目也会更方便😁。