Nuxt 层

Nuxt 提供了一个强大的系统，允许你扩展默认文件、配置等。

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

用例

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

使用方法

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

图层自动注册在 Nuxt v3.12.0 中引入。

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

命名图层别名在 Nuxt v3.16.0 中引入。

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

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

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

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // 每个图层的配置
    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }],
  ],
})
如果未指定分支，则默认为克隆 main 分支。
你可以通过在图层源旁的选项中指定别名来覆盖图层的别名。
nuxt.config.ts
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/       # 最高优先级（在图层间）
此模式适合创建带有默认配置的基础图层，并允许更具体的图层逐层覆盖。

Alternatively, you can control the order of your ~~/layers directories from nuxt.config by referencing them in extends, without renaming your directories. The entries are ordered like any other extends layer, with the first entry having the highest priority:

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '~~/layers/admin', // 最高优先级
    '~~/layers/features',
    '~~/layers/base', // 最低优先级（在列出的图层中）
  ],
})

Both ~~/... (recommended) and ~/... alias forms as well as relative paths (./layers/admin) are supported. Any layer in ~~/layers that you do not list keeps its alphabetical auto-scan order, ranked below the layers you list in extends.

何时使用各自方式

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

使用 extends 的完整示例

nuxt.config.ts
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 中的任何内容。

了解如何使用 layers/ 目录 来组织和共享可重用的代码、组件、组合函数和配置，贯穿你的 Nuxt 应用。
在 图层作者指南（Layer Author Guide） 中可了解有关图层的更多信息。

请提供需要翻译的 Markdown 内容。