Nuxt 层

Nuxt 的核心特性之一是图层（layers）和扩展支持。你可以扩展一个默认的 Nuxt 应用以重用组件、工具函数和配置。图层的结构几乎与标准的 Nuxt 应用相同，这使得它们易于编写和维护。

用例

• 使用 nuxt.config 和 app.config 在多个项目间共享可复用的配置预设
• 使用 app/components/ 目录创建组件库
• 使用 app/composables/ 和 app/utils/ 目录创建工具和可组合函数库
• 创建 Nuxt 模块预设
• 在项目间共享标准设置
• 创建 Nuxt 主题
• 通过实现模块化架构并在大型项目中支持领域驱动设计（DDD）模式来增强代码组织

使用方法

默认情况下，你项目中 ~~/layers 目录内的任何图层都会被自动注册为项目中的图层。

此外，还会自动为这些图层的 srcDir 创建命名图层别名。例如，你将能够通过 #layers/test 访问 ~~/layers/test 图层。

另外，你也可以通过在你的 nuxt.config 文件中添加 extends 属性来从某个图层进行扩展。

export default defineNuxtConfig({
  extends: [
    // 从本地图层扩展
    '../base',
    // 从已安装的 npm 包扩展
    '@my-themes/awesome',
    // 从 git 仓库扩展
    'github:my-themes/awesome#v1',
  ],
})

如果你从私有的 GitHub 仓库扩展，也可以传递认证令牌：

export default defineNuxtConfig({
  extends: [
    // 每个图层的配置
    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }],
  ],
})

export default defineNuxtConfig({
  extends: [
    [
      'github:my-themes/awesome',
      {
        meta: {
          name: 'my-awesome-theme',
        },
      },
    ],
  ],
})

Nuxt 使用 unjs/c12 和 unjs/giget 来扩展远程图层。查看文档以获取更多信息和所有可用选项。

图层优先级

优先级顺序

从高到低优先级：

1. 你的项目文件 — 始终具有最高优先级
2. ~~/layers 目录中自动扫描的本地图层 — 按字母顺序排序（Z 比 A 优先）
3. extends 配置中的图层 — 越靠前的条目优先级越高

示例

考虑多个图层定义同一组件：

layers/
  1.base/
    app/components/Button.vue    # 基础按钮样式
  2.theme/
    app/components/Button.vue    # 主题按钮（覆盖基础样式）
app/
  components/Button.vue          # 项目内按钮（覆盖所有图层）

在这种情况下：

• 如果只有图层，则使用 2.theme/Button.vue（字母序更后，优先级更高）
• 如果你的项目内存在 app/components/Button.vue，则它会覆盖所有图层

控制优先级

你可以为图层目录添加数字前缀以控制其顺序：

layers/
  1.base/        # 最低优先级
  2.features/    # 中等优先级
  3.admin/       # 最高优先级（在图层间）

何时使用哪种方式

• ~~/layers 目录 — 用于属于你项目的本地图层
• extends — 用于外部依赖（npm 包、远程仓库）或位于项目目录外的图层

使用 extends 的完整示例

export default defineNuxtConfig({
  extends: [
    '../base', // 项目外部的本地图层
    '@my-themes/awesome', // NPM 包
    'github:my-themes/awesome#v1', // 远程仓库
  ],
})

如果你还有 ~~/layers/custom，优先级顺序为：

• 你的项目文件（最高）
• ~~/layers/custom
• ../base
• @my-themes/awesome
• github:my-themes/awesome#v1（最低）

这意味着你的项目文件会覆盖任何图层，而 ~~/layers/custom 会覆盖 extends 中的任何内容。

示例