Nuxt Layers - 进阶内容 - Nuxt 中文文档

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

Read more in Docs > Getting Started > Layers.

一个最小的 Nuxt Layers 目录应该包含一个 nuxt.config.ts 文件，以指示它是一个层。

base/nuxt.config.ts

export default defineNuxtConfig({})

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

components/* - 扩展默认组件
composables/* - 扩展默认合成器
layouts/* - 扩展默认布局
pages/* - 扩展默认页面
plugins/* - 扩展默认插件
server/* - 扩展默认服务器端点和中继器
utils/* - 扩展默认工具
nuxt.config.ts - 扩展默认 nuxt 配置
app.config.ts - 扩展默认应用程序配置

基本示例

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

发布层

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

Git 存储库

您可以使用 Git 存储库分享您的 Nuxt Layers。一些示例：

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> 直接配置 nuxt.config 中的 auth 选项。

Bear in mind that if you are extending a remote source as a layer, you will not be able to access its dependencies outside of Nuxt. For example, if the remote layer depends on an eslint plugin, this will not be usable in your eslint config. That is because these dependencies will be located in a special location (node_modules/.c12/layer_name/node_modules/) that is not accessible to your package manager.

当使用 git 远程源时，如果层有 npm 依赖项，并且您希望安装它们，您可以通过指定 安装: 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: [
    // 具有范围的节点模块
    '@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"
  }
}

确保在层中导入的任何依赖项都 显式添加 到 依赖。nuxt 依赖和仅用于在发布层前测试的任何内容应保留在 开发依赖 字段中。

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

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

提示

相对路径和别名

当使用别名（例如 ~/ 和 @/）在层组件和合成器中导入时，请注意别名是相对于用户项目路径解析的。作为 workaround，您可以使用 相对路径 来导入它们。我们正在努力为命名层别名提供更好的解决方案。

同样，当在层的 nuxt.config 文件中使用相对路径时，（除了嵌套 扩展）它们是相对于用户的项目而不是层解析的。作为 workaround，在 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 模块的多层支持

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

modules/my-module.ts

export default defineNuxtModule({
  setup(_options, nuxt) {
    for (const layer of nuxt.options._layers) {
      // 您可以在每个层检查自定义目录的存在以进行扩展
      console.log('Custom extension for', layer.cwd, layer.config)
    }
  }
})

备注:

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

深入探讨

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

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

Nuxt App

在 Nuxt 3 中，您可以在组合式、组件和插件中访问运行时 app 上下文。

调试

在 Nuxt 3 中，您可以直接在浏览器中开始调试您的应用程序，也可以在您的 IDE 中开始调试。