实验性功能
可以在 Nuxt 配置文件中启用 Nuxt 实验性功能。
Nuxt 内部使用 @nuxt/schema
来定义这些实验性功能。您可以参考API 文档 或 源代码 获取更多信息。
asyncContext
启用原生 async 上下文,使其在 Nuxt 和 Nitro 中的嵌套组合式函数中可访问。这使得可以在异步组合式函数内部使用其他组合式函数,并减少出现 Nuxt instance is unavailable
错误的概率。
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
}
})
treeshakeClientOnly
对只在客户端使用的组件的内容进行 Tree Shake,从服务器包中剔除。
默认启用。
export default defineNuxtConfig({
experimental: {
treeshakeClientOnly: true
}
})
emitRouteChunkError
当加载 vite/webpack 分块失败时,触发 app:chunkError
钩子。默认行为是在导航到新路由时,若分块加载失败则刷新新路由。
若设置为 'automatic-immediate'
,则 Nuxt 会立即刷新当前路由,而不是等待导航。这对于非导航触发的分块错误(例如,Nuxt 应用加载懒组件失败)非常有用。但此行为可能导致不必要的刷新,例如应用不需要导致错误分块时。
可以通过设置为 false
禁用自动处理,或设置为 manual
手动处理分块错误。
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // 或 'automatic-immediate', 'manual' 或 false
}
})
restoreState
允许 Nuxt 应用在页面因分块错误或手动调用 reloadNuxtApp()
后从 sessionStorage
恢复状态。
为避免水合错误,此功能仅在 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
启用使用 Speculation Rules API 的跨源预取。
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
viewTransition
启用 View Transition API 与客户端路由器集成。
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
writeEarlyHints
使用 Node 服务器时启用写入早期提示。
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
componentIslands
启用实验性的组件岛屿支持,包括 <NuxtIsland>
组件和 .island.vue
文件。
export default defineNuxtConfig({
experimental: {
componentIslands: true // 也可设置为 false 或 'local+remote'
}
})
configSchema
启用配置模式支持。
默认启用。
export default defineNuxtConfig({
experimental: {
configSchema: true
}
})
polyfillVueUseHead
为依赖旧版 @vueuse/head
API 的模块、插件或用户代码添加兼容层。
export default defineNuxtConfig({
experimental: {
polyfillVueUseHead: false
}
})
respectNoSSRHeader
允许通过设置 x-nuxt-no-ssr
头部禁用 Nuxt SSR 响应。
export default defineNuxtConfig({
experimental: {
respectNoSSRHeader: false
}
})
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
作为 devDependency 安装才能使用此功能。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`)中,若未将路由 slug 反映到键中,则不安全。
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 会在客户端构建中自动使用 unenv
为 Node.js 导入进行 polyfill。
Buffer
,需手动注入:import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
允许在构建时向模块暴露通过 definePageMeta
定义的部分路由元数据(具体包含 alias
、name
、path
、redirect
、props
和 middleware
)。
仅支持静态值或字符串/数组,不支持变量或条件赋值。详情见原始 Issue。
也可以选择在所有路由通过 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 -->
这避免了客户端专用页面水合时的白屏闪烁。
browserDevtoolsTiming
启用浏览器开发者工具中 Nuxt 钩子的性能标记。你可以在基于 Chromium 的浏览器的性能(Performance)标签页中跟踪这些标记,对于调试和优化性能非常有用。
开发模式下默认启用。若需要禁用,配置如下:
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
启用全局装饰器语法,基于 esbuild 实现。
TypeScript 长期通过 compilerOptions.experimentalDecorators
支持装饰器,但该实现早于 TC39 标准流程。现今装饰器为 Stage 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 以前的 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
}
})
granularCachedData
控制刷新 useAsyncData
和 useFetch
数据时(通过 watch
、refreshNuxtData()
或手动调用 refresh()
)是否调用并使用 getCachedData
结果。
export default defineNuxtConfig({
experimental: {
granularCachedData: true
}
})
pendingWhenIdle
若设置为 false
,useAsyncData
、useFetch
、useLazyAsyncData
和 useLazyFetch
返回的 pending
对象会变成计算属性,仅当 status
为 pending 时为 true
。
这意味着传入 immediate: false
时,pending
直到首次请求发起前都是 false
。
export default defineNuxtConfig({
experimental: {
pendingWhenIdle: false
}
})