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

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

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

## 用例

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

## 使用方法

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

<note>

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

</note>

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

<note>

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

</note>

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

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

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

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

<note>

如果未指定分支，则默认为克隆 `main` 分支。

</note>

<tip>

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

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

</tip>

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

## 图层优先级

### 优先级顺序

从高到低优先级：

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

### 示例

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

```bash [目录结构]
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`，则它会覆盖所有图层

### 控制优先级

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

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

<tip>

此模式适合创建带有默认配置的基础图层，并允许更具体的图层逐层覆盖。

</tip>

或者，你可以在 `nuxt.config` 中通过在 [`extends`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#extends) 中引用 `~~/layers` 目录来控制它们的顺序，而无需重命名目录。条目的排序方式与其他 `extends` 图层相同，其中**第一个条目具有最高优先级**：

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

支持 `~~/...`（推荐）和 `~/...` 别名形式，以及相对路径（`./layers/admin`）。任何未列出的 `~~/layers` 中的图层都会保持其按字母顺序自动扫描的顺序，优先级低于你在 `extends` 中列出的图层。

### 何时使用各自方式

- **~~/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/4.x/directory-structure/layers">

了解 **layers/ 目录**，以便在 Nuxt 应用中组织和共享可重用代码、组件、组合式函数和配置。

</read-more>

<read-more to="https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/layers">

在 **Layer Author Guide** 中阅读更多关于图层的内容。

</read-more>

<video-accordion title="观看 Learn Vue 关于 Nuxt 图层的视频" video-id="lnFCM7c9f7I">



</video-accordion>

<video-accordion title="观看 Alexander Lichter 关于 Nuxt 图层的视频" video-id="fr5yo3aVkfA">



</video-accordion>

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


## Sitemap

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