---
title: "层级结构"
description: "Nuxt 提供了一个强大的系统，允许你扩展默认的文件、配置等多种内容。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/getting-started/layers"
---
# 层级结构

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

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

## 使用场景

- 使用 `nuxt.config` 和 `app.config` 在项目之间共享可复用的配置预设
- 使用 [`components/`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/components) 目录创建组件库
- 使用 [`composables/`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/composables) 和 [`utils/`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/utils) 目录创建工具函数和组合式函数库
- 创建 Nuxt 模块预设
- 在项目之间共享标准配置
- 创建 Nuxt 主题
- 通过实现模块化架构并在大型项目中支持领域驱动设计（DDD）模式，改进代码组织。

## 使用方法

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

::note
图层自动注册功能自 Nuxt v3.12.0 起引入。
::

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

::note
命名图层别名功能自 Nuxt v3.16.0 起引入。
::

此外，你可以在 [`nuxt.config`](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/nuxt-config) 文件中添加 [extends](https://nuxt.zhcndoc.com/docs/3.x/api/nuxt-config#extends) 属性，以扩展图层。

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

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

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: [
    // 针对单个图层配置
    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }]
  ]
})
```

::note
如果未指定分支，默认会克隆 `main` 分支。
::

::tip
你可以通过在图层源旁边指定选项来覆盖图层别名。

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

Nuxt 使用了 [unjs/c12](https://github.com/unjs/c12) 和 [unjs/giget](https://github.com/unjs/giget) 来扩展远程图层。请查看文档以获取更多信息和所有可用选项。

## 图层优先级

使用多个图层时，了解覆盖顺序很重要。当多个图层定义相同的文件或组件时，**优先级更高**的图层会覆盖优先级较低的图层。

### 优先级顺序

优先级从高到低为：

1. **你的项目文件** - 始终具有最高优先级
2. 来自 `~~/layers` 目录的 **自动扫描图层** - 按字母顺序排序（Z 的优先级高于 A）
3. 配置中 `extends` 中的图层 - 第一项优先级高于第二项

### 何时使用各自方式

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

::tip
如果你需要控制自动扫描图层的顺序，可以给它们添加数字前缀：`~/layers/1.z-layer`、`~/layers/2.a-layer`。这样 `2.a-layer` 的优先级会高于 `1.z-layer`。
::

### 示例

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

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

在这种情况下：

- 如果只有图层存在，使用 `2.theme/Button.vue`（字母序较高）
- 如果项目中存在 `components/Button.vue`，则覆盖所有图层

### 控制优先级

你可以通过给图层目录加数字前缀来控制顺序：

```bash [目录结构]
layers/
  1.base/        # 优先级最低
  2.features/    # 中等优先级
  3.admin/       # 最高优先级（图层中）
```

::tip
这种模式适用于创建带有默认配置的基础图层，然后由更具体的图层逐步覆盖。
::

### 何时使用各自方式

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

### 完整示例（使用 extends）

```ts [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` 中的任何内容。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/layers"}
了解 **layers/ 目录**，以便在 Nuxt 应用中组织和共享可复用的代码、组件、组合式函数和配置。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/layers"}
在 **图层作者指南** 中了解有关图层的更多信息。
::

::video-accordion{title="观看 Learn Vue 关于 Nuxt 图层的视频" videoId="lnFCM7c9f7I"}
::

::video-accordion{title="观看 Alexander Lichter 关于 Nuxt 图层的视频" videoId="fr5yo3aVkfA"}
::

## 示例

::card-group
  :::card
  ```yaml [props]
  icon: i-simple-icons-github
  title: Content Wind
  to: https://github.com/Atinux/content-wind
  target: _blank
  ```
  一个轻量级的 Nuxt 主题，用于构建基于 Markdown 的网站。基于 Nuxt Content、TailwindCSS 和 Iconify。
  :::
::


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.