创作Nuxt层 Authoring Nuxt Layers

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

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

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

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

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

  • components/* - 扩展默认组件
  • composables/* - 扩展默认可组合项
  • pages/* - 扩展默认页面
  • server/* - 扩展默认服务器端点和中间件
  • nuxt.config.ts - 扩展默认的 nuxt 配置
  • app.config.ts - 扩展默认应用配置

Basic Example

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

入门模板

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

bash
npx nuxi init --template layer nuxt-layer

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

检查 nuxt-themes/starter 以获得更自以为是的创作 Nuxt 主题的入门。 它可以用以下方式初始化：

bash
npx nuxi init --template gh:nuxt-themes/starter my-theme

发布层

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

Git 仓库

您可以使用 git 存储库来共享您的 Nuxt 层。 一些例子：

nuxt.config.ts
ts
export default defineNuxtConfig({
  extends: [
    'github:username/repoName', // GitHub 远程源
    'github:username/repoName/base', // /base 目录中的 GitHub 远程源
    'github:username/repoName#dev', // 来自 dev 分支的 GitHub 远程源
    'github:username/repoName#v1.0.0', // 来自 v1.0.0 标签的 GitHub 远程源
    'gitlab:username/repoName', // GitLab 远程源示例
    'bitbucket:username/repoName', // Bitbucket 远程源示例
  ]
})

如果要扩展私有远程源，则需要添加环境变量 GIGET_AUTH=<token> 以提供令牌。

目前，对于 git 远程源，如果某个层具有 npm 依赖项，您将需要在目标项目中手动安装它们。 我们正在努力使用 git 源自动安装层依赖项。

npm Package

您可以将 Nuxt 层发布为包含您要扩展的文件和依赖项的 npm 包。 这允许您与其他人共享您的配置，在多个项目中使用它或私下使用它。 要从 npm 包进行扩展，您需要确保该模块已发布到 npm 并作为 devDependency 安装在用户的项目中。 然后你可以使用模块名称来扩展当前的 nuxt 配置：

nuxt.config.ts
ts
export default defineNuxtConfig({
  extends: [
    // 具有作用域的节点模块
    '@scope/moduleName',
    // 或者只是模块名称
    'moduleName'
  ]
})

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

package.json
json
{
  "name": "my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./nuxt.config.ts",
  "dependencies": {},
  "devDependencies": {
    "nuxt": "^3.0.0"
  }
}

确保层中导入的任何依赖项都明确添加到“依赖项”中。 nuxt 依赖项，以及任何仅用于在发布前测试层的内容，都应保留在 devDependencies 字段中。

现在您可以继续将模块公开或私下发布到 npm。

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

Tips

相对路径和别名

在层组件和可组合项中使用别名(例如“~/”和“@/”)导入时，请注意别名是相对于用户的项目路径解析的。 作为解决方法，您可以使用相对路径来导入它们。 我们正在为命名层别名开发更好的解决方案。

此外，当在层的nuxt.config文件中使用相对路径时，(嵌套的extends除外)它们是相对于用户项目而不是层解析的。

作为解决方法，在 nuxt.config 中使用完整的解析路径：

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

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

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

Nuxt 模块的多层支持

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

Example:

modules/my-module.ts
js
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 支持源。 查看文档和源代码以了解更多信息。

我们正在努力为层结构带来更多改进。 请参考 nuxt/nuxt#13367。