层级结构

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

使用场景

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

使用方法

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

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

此外，你可以通过在 nuxt.config 文件中添加 extends 属性来扩展某个图层。

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

如果你从私有 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 中的图层 - 第一项优先级高于第二项

何时使用各自方式

• extends - 用于外部依赖（npm 包、远程仓库）或项目目录外的图层
• ~~/layers 目录 - 用于作为你项目一部分的本地图层

示例

假设多个图层定义了相同的组件：

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

在这种情况下：

• 如果只有图层存在，使用 2.theme/Button.vue（字母序较高）
• 如果项目中存在 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 中的任何内容。

示例