实验性功能

启用 Nuxt 实验性功能,解锁更多可能。

可以在 Nuxt 配置文件中启用 Nuxt 实验性功能。

Nuxt 内部使用 @nuxt/schema 来定义这些实验性功能。您可以参考API 文档源代码 获取更多信息。

请注意,这些功能是实验性的,将来可能会被移除或修改。

asyncContext

启用原生 async 上下文,使其在 Nuxt 和 Nitro 中的嵌套组合式函数中可访问。这使得可以在异步组合式函数内部使用其他组合式函数,并减少出现 Nuxt instance is unavailable 错误的概率。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})
在 GitHub 拉取请求中查看完整说明。

asyncEntry

启用为 Vue 包生成异步入口点,有助于模块联邦支持。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    asyncEntry: true
  }
})

externalVue

构建时将 vue@vue/*vue-router 外部化。

默认启用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    externalVue: true
  }
})
该功能可能在不久的将来被移除。

treeshakeClientOnly

对只在客户端使用的组件的内容进行 Tree Shake,从服务器包中剔除。

默认启用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    treeshakeClientOnly: true
  }
})

emitRouteChunkError

当加载 vite/webpack 分块失败时,触发 app:chunkError 钩子。默认行为是在导航到新路由时,若分块加载失败则刷新新路由。

若设置为 'automatic-immediate',则 Nuxt 会立即刷新当前路由,而不是等待导航。这对于非导航触发的分块错误(例如,Nuxt 应用加载懒组件失败)非常有用。但此行为可能导致不必要的刷新,例如应用不需要导致错误分块时。

可以通过设置为 false 禁用自动处理,或设置为 manual 手动处理分块错误。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic' // 或 'automatic-immediate', 'manual' 或 false
  }
})

restoreState

允许 Nuxt 应用在页面因分块错误或手动调用 reloadNuxtApp() 后从 sessionStorage 恢复状态。

为避免水合错误,此功能仅在 Vue 应用挂载后应用,这意味着初次加载时可能出现闪烁。

开启此功能前请谨慎考虑,可能引发意外行为, 并建议为 useState 指定显式键名,因为自动生成的键名在不同构建间可能不匹配。
nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    restoreState: true
  }
})

inlineRouteRules

使用 defineRouteRules 在页面级别定义路由规则。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true
  }
})

将基于页面的 path 创建匹配的路由规则。

阅读更多关于 defineRouteRules 工具。
Read more in Docs > Guide > Concepts > Rendering#hybrid Rendering.

renderJsonPayloads

允许渲染包含复杂类型复活支持的 JSON 负载。

默认启用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: true
  }
})

noVueServer

禁用 Nitro 中的 Vue 服务端渲染端点。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    noVueServer: true
  }
})

payloadExtraction

启用提取使用 nuxt generate 生成页面的负载。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true
  }
})

clientFallback

启用实验性的 <NuxtClientFallback> 组件,当 SSR 出错时在客户端渲染内容。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    clientFallback: true
  }
})

crossOriginPrefetch

启用使用 Speculation Rules API 的跨源预取。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true
  }
})
阅读更多关于 Speculation Rules API

viewTransition

启用 View Transition API 与客户端路由器集成。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    viewTransition: true
  }
})
阅读更多关于 View Transition API

writeEarlyHints

使用 Node 服务器时启用写入早期提示。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    writeEarlyHints: true
  }
})

componentIslands

启用实验性的组件岛屿支持,包括 <NuxtIsland> 组件和 .island.vue 文件。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    componentIslands: true // 也可设置为 false 或 'local+remote'
  }
})
Read more in Docs > Guide > Directory Structure > Components#server Components.
你可以在 GitHub 上关注服务器组件的路线图。

configSchema

启用配置模式支持。

默认启用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    configSchema: true
  }
})

polyfillVueUseHead

为依赖旧版 @vueuse/head API 的模块、插件或用户代码添加兼容层。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    polyfillVueUseHead: false
  }
})

respectNoSSRHeader

允许通过设置 x-nuxt-no-ssr 头部禁用 Nuxt SSR 响应。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    respectNoSSRHeader: false
  }
})

localLayerAliases

解析位于层内的 ~~~@@@ 别名,基于其层源和根目录。

默认启用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    localLayerAliases: true
  }
})

typedPages

启用新的实验性类型化路由,使用 unplugin-vue-router

nuxt.config.ts
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 监视源目录下的所有文件。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular' // 可选 'chokidar' 或 'parcel'
  }
})

sharedPrerenderData

启用此功能后,自动在预渲染页面间共享负载数据。这在使用 useAsyncDatauseFetch 并在多个页面中获取相同数据的站点预渲染时,能显著提升性能。

nuxt.config.ts
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 定义的部分路由元数据(具体包含 aliasnamepathredirectpropsmiddleware)。

仅支持静态值或字符串/数组,不支持变量或条件赋值。详情见原始 Issue

也可以选择在所有路由通过 pages:extend 注册后扫描页面元数据,此时会触发另一个钩子 pages:resolved。启用此行为请设置 scanPageMeta: 'after-resolve'

若该功能引发问题,亦可禁用。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: false
  }
})

cookieStore

启用 CookieStore 支持,监听浏览器 Cookie 更新(如果浏览器支持),并刷新 useCookie 的响应式值。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    cookieStore: true
  }
})
阅读更多关于 CookieStore

buildCache

基于配置和源码文件的哈希缓存 Nuxt 构建产物。

nuxt.config.ts
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 能声明其缓存产物及哈希)。

最多保留 10 个缓存压缩包。

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 组件名称与用于自动导入组件时的完整组件名一致。

nuxt.config.ts
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)标签页中跟踪这些标记,对于调试和优化性能非常有用。

开发模式下默认启用。若需要禁用,配置如下:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    browserDevtoolsTiming: false
  }
})
查看 PR #29922 的实现细节。
了解更多 Chrome DevTools Performance API。

debugModuleMutation

记录模块上下文中对 nuxt.options 的变更,有助于调试 Nuxt 初始化期间模块对配置的修改。

当启用 debug 模式时此功能默认开启。若需禁用,可使用:

若需显式启用:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    debugModuleMutation: true
  }
})
查看 PR #30555 的实现细节。

lazyHydration

<Lazy> 组件启用懒加载水合策略,延迟组件水合以提升性能。

默认启用,若需禁用:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    lazyHydration: false
  }
})
阅读更多关于懒加载水合。

templateImportResolution

控制 Nuxt 模板中导入解析方式。默认情况下,Nuxt 尝试相对于添加导入的模块解析导入。

默认启用,若在某些环境出现解析冲突,可禁用:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    templateImportResolution: false
  }
})
查看 PR #31175 的实现细节。

decorators

启用全局装饰器语法,基于 esbuild 实现。

TypeScript 长期通过 compilerOptions.experimentalDecorators 支持装饰器,但该实现早于 TC39 标准流程。现今装饰器为 Stage 3 提案,TS 5.0+ 无需特殊配置支持该提案(见 https://github.com/microsoft/TypeScript/pull/52582https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators)。

启用 experimental.decorators 支持 TC39 提案语法, TypeScript 以前的 experimentalDecorators 实现。

注意该语法可能在最终定稿前依然会有变动。

使用方法

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    decorators: true,
  },
})
app.vue
function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// 返回 'decorated'

purgeCachedData

Nuxt 会自动清理 useAsyncDatanuxtApp.static.data 的缓存数据,帮助防止内存泄漏,并确保必要时加载最新数据。可通过配置关闭此功能:

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false
  }
})
查看 PR #31379 的实现细节。

granularCachedData

控制刷新 useAsyncDatauseFetch 数据时(通过 watchrefreshNuxtData() 或手动调用 refresh())是否调用并使用 getCachedData 结果。

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    granularCachedData: true
  }
})
查看 PR #31373 的实现细节。

pendingWhenIdle

若设置为 falseuseAsyncDatauseFetchuseLazyAsyncDatauseLazyFetch 返回的 pending 对象会变成计算属性,仅当 status 为 pending 时为 true

这意味着传入 immediate: false 时,pending 直到首次请求发起前都是 false

nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: false
  }
})