实验性功能

启用 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
  }
})

Read and edit a live example in https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue.

阅读更多关于 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

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

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 定义的部分路由元数据（具体包含 alias、name、path、redirect、props 和 middleware）。

仅支持静态值或字符串/数组，不支持变量或条件赋值。详情见原始 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.lock
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/52582 和 https://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 会自动清理 useAsyncData 和 nuxtApp.static.data 的缓存数据，帮助防止内存泄漏，并确保必要时加载最新数据。可通过配置关闭此功能：

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false
  }
})

查看 PR #31379 的实现细节。

granularCachedData

控制刷新 useAsyncData 和 useFetch 数据时（通过 watch、refreshNuxtData() 或手动调用 refresh()）是否调用并使用 getCachedData 结果。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    granularCachedData: true
  }
})

查看 PR #31373 的实现细节。

pendingWhenIdle

若设置为 false，useAsyncData、useFetch、useLazyAsyncData 和 useLazyFetch 返回的 pending 对象会变成计算属性，仅当 status 为 pending 时为 true。

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

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: false
  }
})

Was this helpful?

报告问题或者在 GitHub 上编辑此页面

事件

Nuxt 提供了一个强大的事件系统，由 hookable 驱动。

特性

启用或禁用可选的 Nuxt 特性以解锁新的可能性。