实验特性
Nuxt 实验特性可以在 Nuxt 配置文件中启用。
在内部,Nuxt 通过 @nuxt/schema
来定义这些实验特性。你可以参考 API 文档 或 源代码 获取更多信息。
asyncContext
启用本地异步上下文,使其可以被嵌套的组合函数访问。这为在异步组合函数内部使用组合函数打开了可能性,并减少了出现 Nuxt 实例不可用
错误的机会。
export default defineNuxtConfig({
experimental: {
asyncContext: true
}
})
asyncEntry
为 Vue 包生成异步入口点,帮助模块联邦支持。
export default defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
externalVue
在构建时外部化 vue
、@vue/*
和 vue-router
。
默认启用。
export default defineNuxtConfig({
experimental: {
externalVue: true
}
})
emitRouteChunkError
当加载 vite/webpack 块时发生错误时发出 app:chunkError
钩子。默认行为是在导航到新路由时重新加载新路由,当块加载失败时。
如果将其设置为 'automatic-immediate'
,Nuxt 将立即重新加载当前路由,而不是等待导航。这对于不是由导航触发的块错误非常有用,例如,当你的 Nuxt 应用无法加载 懒组件 时。此行为的潜在缺点是可能导致不必要的重新加载,例如,当你的应用不需要导致错误的块时。
你可以通过将其设置为 false
来禁用自动处理,或通过将其设置为 manual
来手动处理块错误。
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // 或 'automatic-immediate','manual' 或 false
}
})
restoreState
允许在页面重新加载后从 sessionStorage
恢复 Nuxt 应用状态,以应对块错误或手动 reloadNuxtApp()
调用。
为了避免水合错误,它将仅在 Vue 应用已挂载后应用,这意味着在初始加载时可能会出现闪烁。
useState
提供显式键,因为自动生成的键可能在构建之间不匹配。export default defineNuxtConfig({
experimental: {
restoreState: true
}
})
inlineRouteRules
使用 defineRouteRules
在页面级别定义路由规则。
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true
}
})
将根据页面的 path
创建匹配的路由规则。
renderJsonPayloads
允许渲染 JSON 有效负载,并支持复生复杂类型。
默认启用。
export default defineNuxtConfig({
experimental: {
renderJsonPayloads: true
}
})
noVueServer
在 Nitro 内禁用 Vue 服务器渲染端点。
export default defineNuxtConfig({
experimental: {
noVueServer: true
}
})
payloadExtraction
启用从使用 nuxt generate
生成的页面中提取有效负载。
export default defineNuxtConfig({
experimental: {
payloadExtraction: true
}
})
clientFallback
启用实验性的 <NuxtClientFallback>
组件,用于在 SSR 中出现错误时渲染客户端内容。
export default defineNuxtConfig({
experimental: {
clientFallback: true
}
})
crossOriginPrefetch
启用使用猜测规则 API 的跨域预获取。
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
viewTransition
启用 View Transition API 与客户端路由器的集成。
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
writeEarlyHints
启用在使用节点服务器时写入早期提示。
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
componentIslands
启用实验性的组件岛支持,使用 <NuxtIsland>
和 .island.vue
文件。
export default defineNuxtConfig({
experimental: {
componentIslands: true // false 或 'local+remote'
}
})
localLayerAliases
解析位于层中的 ~
、~~
、@
和 @@
别名,尊重其层源和根目录。
默认启用。
export default defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
typedPages
启用新的实验性类型路由,使用 unplugin-vue-router
。
export default defineNuxtConfig({
experimental: {
typedPages: true
}
})
开箱即用,这将启用 navigateTo
、<NuxtLink>
、router.push()
等的类型安全用法。
你甚至可以通过使用 const route = useRoute('route-name')
来获取页面中的类型参数。
pnpm
,而没有设置 shamefully-hoist=true
,你需要将 unplugin-vue-router
作为开发依赖安装,以使此功能正常工作。watcher
设置一个替代的观察者,将作为 Nuxt 的观察服务使用。
Nuxt 默认使用 chokidar-granular
,它将忽略顶层目录(如 node_modules
和 .git
),这些目录被排除在观察之外。
你可以将其设置为 parcel
,以使用 @parcel/watcher
,这可能在大型项目或 Windows 平台上提高性能。
你还可以将其设置为 chokidar
,以观察源目录中的所有文件。
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular' // 'chokidar' 或 'parcel' 也是选项
}
})
sharedPrerenderData
启用此功能会自动在预渲染的页面之间共享有效负载 数据。这能够在预渲染使用 useAsyncData
或 useFetch
并在不同页面中获取相同数据的网站时显著提升性能。
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: true
}
})
在启用此功能时,确保你的数据的任何唯一键始终可解析到相同的数据非常重要。例如,如果你使用 useAsyncData
获取与特定页面相关的数据,你应该提供一个唯一匹配该数据的键。(useFetch
应该为你自动执行此操作。)
// 在动态页面(例如 `[slug].vue`)中,这将是不安全的,因为路由标识符会影响获取的数据,但 Nuxt 无法得知,因为它没有在键中反映。
const route = useRoute()
const { data } = await useAsyncData(async () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
// 相反,你应该使用一个唯一标识所获取数据的键。
const { data } = await useAsyncData(route.params.slug, async () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
clientNodeCompat
启用此功能后,Nuxt 将自动为客户端构建中的 Node.js 导入进行 polyfill,使用 unenv
。
Buffer
这样的全局变量在浏览器中工作,你需要手动注入它们。import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
此选项允许在构建时将 definePageMeta
中定义的一些路由元数据暴露给模块(特别是 alias
、name
、path
、redirect
)。
这仅适用于静态或字符串/数组,而不是变量或条件赋值。有关更多信息和上下文,请参见 原始问题。
此外,只在所有路由在 pages:extend
中注册后才能扫描页面元数据。然后,将调用另一个钩子 pages:resolved
。要启用此行为,可以设置 scanPageMeta: 'after-resolve'
。
如果此功能在你的项目中引起问题,可以禁用它。
export default defineNuxtConfig({
experimental: {
scanPageMeta: false
}
})
cookieStore
启用 CookieStore 支持,以侦听 cookie 更新(如果浏览器支持)并刷新 useCookie
引用值。
export default defineNuxtConfig({
experimental: {
cookieStore: true
}
})
buildCache
根据配置和源文件的哈希缓存 Nuxt 的构建工件。
export default defineNuxtConfig({
experimental: {
buildCache: true
}
})
启用时,对以下文件的更改将触发完整的重建:
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lockb
此外,srcDir
中的文件的任何更改将触发 Vue 客户端/服务器包的重建。Nitro 将始终重新构建(尽管正在进行工作,以允许 Nitro 宣布其可缓存的工件及其哈希)。
extraPageMetaExtractionKeys
definePageMeta()
宏是收集页面构建时元数据的有用方式。Nuxt 本身提供了一组支持的键,作为一些内部特性(如重定向、页面别名和自定义路径)的基础。
此选项允许在使用 scanPageMeta
时传递从页面元数据中提取的附加键。
<script lang="ts" setup>
definePageMeta({
foo: 'bar'
})
</script>
export default defineNuxtConfig({
experimental: {
extraPageMetaExtractionKeys: ['foo'],
},
hooks: {
'pages:resolved' (ctx) {
// ✅ foo 可用
},
},
})
这允许模块在构建上下文中访问页面元数据中的附加元数据。如果你在模块中使用此功能,建议你 使用你的键增强 NuxtPage
类型。
normalizeComponentNames
确保自动生成的 Vue 组件名称与用于自动导入组件的完整组件名称匹配。
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: true
}
})
默认情况下,如果不手动设置,Vue 将为组件分配匹配组件文件名的组件名称。
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
在这种情况下,Vue 认为组件名称为 MyComponent
。如果你希望与之一起使用 <KeepAlive>
,或者在 Vue DevTools 中识别它,你需要使用此组件。
但是,为了自动导入它,你需要使用 SomeFolderMyComponent
。
通过设置 experimental.normalizeComponentNames
,这两个值匹配,Vue 将生成与 Nuxt 组件命名模式匹配的组件名称。
spaLoadingTemplateLocation
在渲染客户端独占页面时(ssr: false
),我们可以选择渲染一个加载屏幕(来自 app/spa-loading-template.html
)。
可以将其设置为 within
,这将像这样渲染:
<div id="__nuxt">
<!-- spa loading template -->
</div>
或者,你可以通过将其设置为 body
,使模板与 Nuxt 应用根级一起渲染:
<div id="__nuxt"></div>
<!-- spa loading template -->
这可以避免在hydration客户端独占页面时出现的白色闪烁。
browserDevtoolsTiming
启用在浏览器开发者工具中记录 Nuxt 钩子的性能标记。这将在基于 Chromium 的浏览器的性能选项卡中添加性能标记,这对于调试和优化性能非常有用。
在开发模式下默认启用。如果需要禁用此功能,可以这样做:
export default defineNuxtConfig({
experimental: {
browserDevtoolsTiming: false
}
})
debugModuleMutation
记录在模块上下文中对 nuxt.options
的变更,帮助调试模块在 Nuxt 初始化阶段所做的配置更改。
当启用 debug
模式时,此功能默认启用。如果需要禁用此功能,可以这样做:
要显式启用它:
export default defineNuxtConfig({
experimental: {
debugModuleMutation: true
}
})
lazyHydration
此功能启用 <Lazy>
组件的水合策略,改善性能,通过推迟组件的水合,直到需要为止。
懒惰水合默认启用,但是你可以禁用此功能:
export default defineNuxtConfig({
experimental: {
lazyHydration: false
}
})
templateImportResolution
控制在 Nuxt 模板中导入的解析方式。默认情况下,Nuxt 尝试相对于添加它们的模块解析模板中的导入。
这默认启用,因此如果在某些环境中遇到解析冲突,可以禁用此行为:
export default defineNuxtConfig({
experimental: {
templateImportResolution: false
}
})
decorators
此选项启用在整个 Nuxt/Nitro 应用中启用装饰器语法,由 esbuild 提供支持。
长期以来,TypeScript 通过 compilerOptions.experimentalDecorators
支持装饰器。此实现早于 TC39 标准化过程。现在,装饰器是一个 阶段 3 提案,在 TS 5.0 及更高版本中支持,而无需特殊配置(参见 https://github.com/microsoft/TypeScript/pull/52582 和 https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators)。
启用 experimental.decorators
可启用 TC39 提案的支持,而不是 TypeScript 先前的 compilerOptions.experimentalDecorators
实现。
使用方式
export default defineNuxtConfig({
experimental: {
decorators: true,
},
})
function something (_method: () => unknown) {
return () => 'decorated'
}
class SomeClass {
@something
public someMethod () {
return 'initial'
}
}
const value = new SomeClass().someMethod()
// 这将返回 'decorated'
purgeCachedData
Nuxt 将自动清除来自 useAsyncData
和 nuxtApp.static.data
的缓存数据。这有助于防止内存泄漏,并确保在需要时加载新数据,但可以选择禁用此功能:
export default defineNuxtConfig({
experimental: {
purgeCachedData: false
}
})