编写 Nuxt 层
Nuxt 层是一项强大的功能,您可以用它在单一代码库中的部分 Nuxt 应用间共享和重用,或者从 git 仓库或 npm 包中共享。层的结构几乎与标准 Nuxt 应用相同,这使得它们易于编写和维护。
一个最小的 Nuxt 层目录应该包含一个 nuxt.config.ts
文件,以指示这是一个层。
export default defineNuxtConfig({})
此外,层目录中的某些其他文件将被 Nuxt 自动扫描并用于扩展此层的项目。
app/components/*
- 扩展默认组件app/composables/*
- 扩展默认 composablesapp/layouts/*
- 扩展默认布局app/middleware/*
- 扩展默认中间件app/pages/*
- 扩展默认页面app/plugins/*
- 扩展默认插件app/utils/*
- 扩展默认 utilsapp/app.config.ts
- 扩展默认 app configserver/*
- 扩展默认 server endpoints & middlewarenuxt.config.ts
- 扩展默认 nuxt config
基本示例
export default defineNuxtConfig({
extends: [
'./base'
]
})
<template>
<BaseComponent/>
</template>
export default defineNuxtConfig({
// 从基础 nuxt.config.ts 扩展!
app: {
head: {
title: '扩展配置是有趣的!',
meta: [
{ name: 'description', content: '我正在使用 Nuxt 的扩展功能!' }
],
}
}
})
<template>
<h1>扩展组件是有趣的!</h1>
</template>
层优先级
从多个层扩展时,了解优先级顺序非常重要:
extends
中的层 - 较早的条目具有更高的优先级(第一个覆盖第二个)- 自动扫描的本地层 来自
~~/layers
目录,按字母顺序排列(Z覆盖A) - 您的项目 在堆栈中具有最高优先级 - 它将始终覆盖其他层
例如:
export default defineNuxtConfig({
extends: [
'./layers/base', // Highest priority (among extends)
'./layers/theme', // Medium priority
'./layers/custom' // Lower priority
]
// 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 层。以下是一些示例:
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>
以提供令牌。GIGET_GITHUB_URL=<url>
或 GIGET_GITLAB_URL=<url>
环境变量提供其 URL - 或直接在 nuxt.config
中使用 auth 选项 进行配置。node_modules/.c12/layer_name/node_modules/
),该位置对您的包管理器不可访问。install: true
来实现。export default defineNuxtConfig({
extends: [
['github:username/repoName', { install: true }]
]
})
npm 包
您可以将 Nuxt 层作为一个 npm 包发布,该包包含您想要扩展的文件和依赖项。这使您可以与他人共享您的配置,或在多个项目中使用它,或者私下使用。
要从 npm 包扩展,您需要确保该模块已发布到 npm,并安装在用户的项目中,作为一个 devDependency。然后,您可以使用模块名称来扩展当前的 nuxt 配置:
export default defineNuxtConfig({
extends: [
// 带作用域的节点模块
'@scope/moduleName',
// 或者只是模块名称
'moduleName'
]
})
要将层目录作为 npm 包发布,您需要确保 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,无论是公开还是私有。
提示
命名层别名
自动扫描的层(来自您的 ~~/layers
目录)会自动创建别名。例如,您可以通过 #layers/test
访问您的 ~~/layers/test
层。
如果您想为其他层创建命名层别名,可以在层的配置中指定一个名称。
export default defineNuxtConfig({
$meta: {
name: 'example',
},
})
这将生成 #layers/example
的别名,指向您的层。
相对路径和别名
在层组件和组合中使用全局别名(如 ~/
和 @/
)导入时,请注意这些别名相对于用户项目路径解析。作为一种解决方法,您可以使用相对路径来导入它们,或使用命名层别名。
同样,在层的 nuxt.config
文件中使用相对路径时(嵌套 extends
的情况除外),它们是相对于用户项目解析,而不是层。作为一种解决方法,请在 nuxt.config
中使用完整解析的路径:
import { fileURLToPath } from 'url'
import { dirname, join } from 'path'
const currentDir = dirname(fileURLToPath(import.meta.url))
export default defineNuxtConfig({
css: [
join(currentDir, './app/assets/main.css')
]
})
Nuxt 模块的多层支持
您可以使用内部数组 nuxt.options._layers
来支持模块的自定义多层处理。
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 进行支持。查看文档和源代码以了解更多信息。