v3.16
Nuxt on GitHub

创建 Nuxt 层

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

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

阅读更多 Docs > Getting Started > Layers.

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

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

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

基本示例

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

启动模板

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

Terminal
npm create nuxt -- --template layer nuxt-layer

按照 README 中的说明进行后续步骤。

发布层

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

Git 仓库

你可以使用 Git 仓库来共享你的 Nuxt 层。以下是一些示例：

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    'github:username/repoName',        // GitHub 远程源
    'github:username/repoName/base',   // GitHub 远程源，位于 /base 目录
    'github:username/repoName#dev',    // GitHub 远程源，来自 dev 分支
    'github:username/repoName#v1.0.0', // GitHub 远程源，来自 v1.0.0 标签
    'gitlab:username/repoName',        // GitLab 远程源示例
    'bitbucket:username/repoName',     // Bitbucket 远程源示例
  ]
})
如果你想扩展一个私有远程源，你需要添加环境变量 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 并在用户项目中作为开发依赖安装。然后，你可以使用模块名称来扩展当前的 Nuxt 配置：

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    // 带作用域的 Node 模块
    '@scope/moduleName',
    // 或仅模块名称
    '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 'url'
import { dirname, join } from 'path'

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

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

多层支持模块

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

modules/my-module.ts
export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // 你可以检查每个层的自定义目录是否存在以进行扩展
      console.log('自定义扩展用于', layer.cwd, layer.config)
    }
  }
})

注意：

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

深入了解

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

在 GitHub 上查看我们为层支持带来更多改进的持续开发。