层 layers
本教程共 50 篇 · 第 39 篇 · 更新于 2026-08-08 · 约 6 分钟阅读
本节目标：理解 Nuxt 的层（Layers）机制，学会用
extends让一个项目继承另一套配置、组件和组合式函数，实现跨项目复用。
39-1
想象你负责公司里五个内部后台，它们的登录页、布局、配色、工具函数几乎一模一样。每次新建一个项目，你都把这套东西复制一遍。改一处样式，五个项目挨个改——这显然不对。
层（Layers）就是用来解决这种「共享一套基础」的需求。你可以把通用部分抽成一个层，其他项目 extends 它，就像子类继承父类：基础层提供默认文件，子项目可以覆盖、追加，也能新增自己的东西。
Note层的结构几乎和普通 Nuxt 应用一样：有自己的
nuxt.config、components/、composables/、pages/等。所以它很容易写、容易维护。
39-2
最常见的用法是在 nuxt.config.ts 里加 extends：
export default defineNuxtConfig({
extends: [
'../base', // 从本地目录扩展
'@my-themes/awesome', // 从已安装的 npm 包扩展
'github:my-themes/awesome#v1', // 从 git 仓库扩展
],
})Nuxt 内部用 c12 和 giget 来拉取远程层（比如 GitHub 上的），所以你甚至能直接从仓库继承一套主题。
39-3
层几乎能包含一套完整 Nuxt 应用的任何部分：
- 通过
nuxt.config和app.config共享配置预设； - 用
components/提供一套组件库； - 用
composables/和utils/提供工具与组合式函数； - 做成主题（theme），统一视觉风格；
- 在大型项目里做领域驱动设计（DDD），按业务拆分模块。
换句话说，你既可以把层当成「公司级基础套件」，也能当成「一个可发布的设计主题」。
39-4
在项目里，~~/layers 目录下的任何层会被自动注册为项目的层（从 Nuxt 3.12 开始支持）。比如：
my-app/
├── nuxt.config.ts
├── layers/
│ └── admin/ # 自动被识别为层
│ ├── nuxt.config.ts
│ └── components/
└── app/每个层的 srcDir 还会自动生成命名别名，例如 ~~/layers/admin 可以通过 #layers/admin 访问（从 Nuxt 3.16 开始）。
39-5
如果层放在私有 GitHub 仓库，你可以传认证令牌：
export default defineNuxtConfig({
extends: [
['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }],
],
})Tip从远程层拉代码时，Nuxt 会按层顺序合并。靠后的层优先级更高，可以覆盖前面层里的同名文件。利用这一点，基础层给默认值，项目层做定制，非常顺手。
39-6
导入顺序要心里有数：多个层里若出现同名组件/组合式函数，后加载的会覆盖先加载的。如果你发现「明明改了基础层，项目里没生效」，多半是被子层覆盖了，或者反过来。
Warning如果你在
nuxt.config里设置了imports.scan: false（关闭自定义代码自动扫描），层的自动导入会失效，你需要在每个层里手动 import。用层时不要顺手关掉自动导入，否则会破坏层的覆盖能力。
39-7
Nuxt 3 与 Nuxt 4 的层机制一致，都用 extends。差异仅在目录：Nuxt 4 的层内部若含源码，目录默认是 app/（或对应子目录），而 Nuxt 3 是根目录。层本身作为独立项目，内部约定跟随它自己的 Nuxt 版本即可。
39-8
三者都能复用代码，但层次不同：
- 插件：应用级一次性初始化，比如挂全局错误处理器。它在运行时生效，不产出可复用文件。
- 模块：构建时运行，能往项目里注入组件、组合式函数、插件、配置。适合「可发布的扩展包」，全站共享。
- 层：项目级的「继承」，能共享一整套
nuxt.config、组件、页面、样式。适合「公司基础套件」或「主题」这种更大块的复用。
一句话：小逻辑用插件，可发布的能力用模块，跨项目的整套骨架用层。层还能 extends 多个，模块也能被多个项目装，它们是互补关系，不是二选一。
39-9
extends 数组里靠后的层优先级更高。基础层给默认值，子项目（或后面的层）可以覆盖同名文件、同名 nuxt.config 字段。理解这一点很关键：当你发现「改了基础层没生效」，先检查是不是被子层或 nuxt.config 里的同名项覆盖了。同名组件也是后加载的胜出。
Warning层级太深（extends 套 extends）会让「某个文件到底来自哪一层」变得难追。层最多两三层就够，过多会让排查成本飙升。
用层做主题时有个实用做法：基础层放一套app.vue、默认nuxt.config和通用组件，子项目只覆盖自己需要的那几个文件，其余全部继承。这样改一处配色，所有子项目统一生效。这也是很多「白标（white-label）」产品用 Nuxt 层的原因——同一套代码，换皮就能交付给不同客户，而不用维护五份几乎一样的仓库。
39-10
层是「项目级的继承」，用 extends 复用配置、组件、组合式函数，适合做公司基础套件或主题。本地层放 ~~/layers 会自动注册，远程层可用 git 仓库。靠顺序控制覆盖。下一章我们看应用的生命周期与钩子。
39-6 层的版本管理与更新
当层被多个项目依赖时，版本管理变得重要。建议用语义化版本号（SemVer）来管理层的版本：修复 bug 升补丁号，新增功能升次版本号，破坏性变更升主版本号。依赖方通过版本号锁定兼容性，避免意外升级导致功能异常。
发布层的方式和普通 npm 包一样。你可以发布到公共 npm 仓库，也可以发布到私有仓库（如 GitHub Packages、Verdaccio）。对于企业内部使用，私有仓库更常见，因为层的代码通常和公司的业务逻辑紧密相关。
更新层之后，依赖方需要执行 npx nuxi upgrade 或重新安装依赖来获取新版本。建议在层的 CHANGELOG 里记录每次更新的内容，方便依赖方评估升级的影响。
39-7 层的测试策略
测试基于层的项目时，有几个值得注意的点。层的代码在被项目引用后，会合并到项目的上下文中运行。因此，层的测试应该既包括独立的单元测试，也包括在宿主项目中的集成测试。
层的单元测试可以直接在层的目录下运行，不需要依赖宿主项目。组合式函数、工具函数、组件逻辑都可以独立测试。集成测试则需要在引用了层的项目里运行，验证层的功能和宿主项目的功能是否协调工作。
建议在层的 CI 流程里同时运行这两种测试。单元测试保证层本身的代码质量，集成测试保证层和宿主项目的兼容性。