编写 Nuxt 层

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

Nuxt 层是一个强大的功能，您可以使用它在 monorepo 中，或从 Git 仓库或 npm 包中共享和重用部分 Nuxt 应用程序。层的结构几乎与标准 Nuxt 应用程序相同，这使得它们易于创作和维护。

在文档 > 4 X > 入门 > 层中阅读更多内容。

一个最小的 Nuxt 层目录应包含一个 nuxt.config.ts 文件，以表明它是一个层。

base/nuxt.config.ts
export default defineNuxtConfig({})

此外，层目录中的某些其他文件将被 Nuxt 自动扫描并用于扩展此层的项目。

基本示例

export default defineNuxtConfig({
  extends: [
    './base',
  ],
})

层优先级

当从多个层扩展时，了解优先级顺序很重要

  1. extends 中的层 - 较早的条目具有较高优先级（第一个覆盖第二个）
  2. 按字母顺序（Z 覆盖 A）从 ~~/layers 目录中自动扫描的本地层
  3. 您的项目在堆栈中具有最高优先级 - 它将始终覆盖其他层

例如

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // Highest priority (among extends)
    './layers/base',
    // Medium priority
    './layers/theme',
    // Lower priority
    './layers/custom',
  ],
  // Your project has the highest priority
})

如果您还有自动扫描的层，例如 ~~/layers/a 和 ~~/layers/z，则完整的覆盖顺序将是：base > theme > custom > z > a > 您的项目。

入门模板

要开始使用，您可以使用nuxt/starter/layer 模板初始化一个层。这将创建一个您可以基于其构建的基本结构。在终端中执行此命令以开始使用

终端
npm create nuxt -- --template layer nuxt-layer

遵循 README 说明以了解后续步骤。

发布层

您可以通过使用远程源或 npm 包来发布和共享层。

Git 仓库

您可以使用 Git 仓库共享您的 Nuxt 层。一些示例：

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // GitHub Remote Source
    'github:username/repoName',
    // GitHub Remote Source within /base directory
    'github:username/repoName/base',
    // GitHub Remote Source from dev branch
    'github:username/repoName#dev',
    // GitHub Remote Source from v1.0.0 tag
    'github:username/repoName#v1.0.0',
    // GitLab Remote Source example
    'gitlab:username/repoName',
    // Bitbucket Remote Source example
    'bitbucket:username/repoName',
  ],
})
如果您想扩展私有远程源，您需要添加环境变量 GIGET_AUTH=<token> 以提供令牌。
如果您想从自托管的 GitHub 或 GitLab 实例扩展远程源，您需要使用 GIGET_GITHUB_URL=<url> 或 GIGET_GITLAB_URL=<url> 环境变量提供其 URL - 或直接通过您 nuxt.config 中的 auth 选项进行配置。
请记住，如果您将远程源作为层扩展，您将无法在 Nuxt 之外访问其依赖项。例如，如果远程层依赖于 eslint 插件，则该插件将无法在您的 eslint 配置中使用。这是因为这些依赖项将位于一个特殊位置（node_modules/.c12/layer_name/node_modules/），您的包管理器无法访问。
当使用 Git 远程源时，如果一个层有 npm 依赖项并且您希望安装它们，您可以通过在层选项中指定 install: true 来实现。
nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    ['github:username/repoName', { install: true }],
  ],
})

npm 包

您可以将 Nuxt 层发布为 npm 包，其中包含您想要扩展的文件和依赖项。这允许您与他人共享您的配置，在多个项目中使用它或私下使用它。

要从 npm 包扩展，您需要确保模块已发布到 npm 并作为 devDependency 安装在用户的项目中。然后您可以使用模块名称来扩展当前的 nuxt 配置。

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // Node Module with scope
    '@scope/moduleName',
    // or just the module name
    'moduleName',
  ],
})

要将层目录发布为 npm 包，您需要确保 package.json 具有正确填充的属性。这将确保文件在包发布时被包含。

package.json
{
  "name": "my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {},
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}
确保层中导入的任何依赖项都明确添加到 dependencies 中。nuxt 依赖项以及仅用于在发布前测试层的任何内容应保留在 devDependencies 字段中。

现在您可以继续将模块发布到 npm，无论是公开还是私下。

当将层发布为私有 npm 包时，您需要确保登录以通过 npm 进行身份验证以下载节点模块。

提示

命名层别名

自动扫描的层（来自您的 ~~/layers 目录）会自动创建别名。例如，您可以通过 #layers/test 访问您的 ~~/layers/test 层。

如果您想为其他层创建命名层别名，可以在层的配置中指定一个名称。

nuxt.config.ts
export default defineNuxtConfig({
  $meta: {
    name: 'example',
  },
})

这将生成一个指向您的层的别名 #layers/example。

相对路径和别名

当在层组件和组合式函数中使用全局别名（例如 ~/ 和 @/）导入时，请注意这些别名是相对于用户项目路径解析的。作为一种变通方法，您可以使用相对路径导入它们，或使用命名层别名。

此外，当在层的 nuxt.config 文件中使用相对路径时（嵌套的 extends 除外），它们是相对于用户项目而不是层解析的。作为一种变通方法，请在 nuxt.config 中使用完整的解析路径。

nuxt.config.ts
import { fileURLToPath } from 'node:url'
import { dirname, join } from 'node:path'

const currentDir = dirname(fileURLToPath(import.meta.url))

export default defineNuxtConfig({
  css: [
    join(currentDir, './app/assets/main.css'),
  ],
})

Nuxt 模块的多层支持

您可以使用内部数组 nuxt.options._layers 来支持模块的自定义多层处理。

modules/my-module.ts
export default defineNuxtModule({
  setup (_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // You can check for a custom directory existence to extend for each layer
      console.log('Custom extension for', layer.cwd, layer.config)
    }
  },
})

注意事项

  • _layers 数组中较早的项目具有较高优先级并覆盖较晚的项目
  • 用户的项目是 _layers 数组中的第一个项目

深入了解

配置加载和扩展支持由unjs/c12处理，使用unjs/defu合并，并使用unjs/giget支持远程 Git 源。查看文档和源代码以了解更多信息。

在 GitHub 上查看我们正在进行的开发，以带来更多层支持的改进。