编写 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. 自动扫描的本地层，来自~~/layers目录，按字母顺序（Z 覆盖 A）
  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 进行身份验证以下载 node 模块。

提示

命名层别名

自动扫描的层（来自您的~~/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 Kit 中的getLayerDirectories实用程序来支持您的模块的自定义多层处理。

modules/my-module.ts
import { defineNuxtModule, getLayerDirectories } from 'nuxt/kit'

export default defineNuxtModule({
  setup (_options, nuxt) {
    const layerDirs = getLayerDirectories()

    for (const [index, layer] of layerDirs.entries()) {
      console.log(`Layer ${index}:`)
      console.log(`  Root: ${layer.root}`)
      console.log(`  App: ${layer.app}`)
      console.log(`  Server: ${layer.server}`)
      console.log(`  Pages: ${layer.appPages}`)
      // ... other directories
    }
  },
})

注意事项

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

深入探索

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

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