使用 Vue & UI Pro 的仪表板模板

编写 Nuxt 层

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

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

文档 > 入门 > 层 中了解更多信息。

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

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

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

基本示例

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

入门模板

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

终端
npx nuxi init --template layer nuxt-layer

请参考 README 指令以了解后续步骤。

发布层

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

Git 仓库

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

nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    'github:username/repoName',        // GitHub Remote Source
    'github:username/repoName/base',   // GitHub Remote Source within /base directory
    'github:username/repoName#dev',    // GitHub Remote Source from dev branch
    'github:username/repoName#v1.0.0', // GitHub Remote Source from v1.0.0 tag
    'gitlab:username/repoName',        // GitLab Remote Source example
    'bitbucket:username/repoName',     // Bitbucket Remote Source example
  ]
})
如果您想扩展私有远程源,您需要添加环境变量 GIGET_AUTH=<token> 来提供令牌。
如果您想从自托管的 GitHub 或 GitLab 实例扩展远程源,您需要使用 GIGET_GITHUB_URL=<url>GIGET_GITLAB_URL=<url> 环境变量提供其 URL - 或者直接使用 您的 nuxt.config 中的 auth 选项 进行配置。
当使用 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 身份验证下载节点模块。

提示

相对路径和别名

在层组件和可组合项中使用别名(如 ~/@/)进行导入时,请注意别名是相对于用户项目路径解析的。作为解决方法,您可以 **使用相对路径** 来导入它们。我们正在努力寻找更好的命名层别名解决方案。

同样,在层的 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 模块的多层支持

您可以使用内部数组 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 数组中的第一项。

深入了解

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

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