实验特性

export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    appManifest: false,
  },
})

export default defineNuxtConfig({
  experimental: {
    asyncContext: true,
  },
})

在 GitHub 拉取请求中查看完整说明。

export default defineNuxtConfig({
  experimental: {
    asyncEntry: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true,
  },
})

<!-- 转换前 -->
<script setup>
const { data } = await useAsyncData('user', async () => {
  return await $fetch('/api/user')
})
</script>

<!-- 转换后 -->
<script setup>
const { data } = await useAsyncData('user', () =>
  import('/generated-chunk.js').then(r => r.default()),
)
</script>

export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic', // 或 'automatic-immediate'、'manual' 或 false
  },
})

export default defineNuxtConfig({
  experimental: {
    enforceModuleCompatibility: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    restoreState: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true,
  },
})

在 defineRouteRules 工具中了解更多信息。

在 Docs > Guide > Concepts > Rendering#hybrid Rendering 中查看详情

export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: false,
  },
})

export default defineNuxtConfig({
  experimental: {
    noVueServer: true,
  },
})

export default defineNuxtConfig({
  future: { compatibilityVersion: 4 },
  experimental: {
    parseErrorData: false,
  },
})

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: 'client',
  },
})

了解更多关于 payload 提取及每种模式后果的信息。

export default defineNuxtConfig({
  experimental: {
    clientNodePlaceholder: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    early404: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    clientFallback: true,
  },
})

export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})

阅读有关 Speculation Rules API 的更多信息。 :::

viewTransition

启用与客户端路由器的视图过渡 API 集成。您也可以传入一个对象来配置视图过渡类型，它允许基于导航类型使用不同的 CSS 动画：

writeEarlyHints

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

componentIslands

使用 <NuxtIsland> 和 .island.vue 文件启用实验性的组件岛（component islands）支持。

localLayerAliases

解析位于 layer 内的 ~、~~、@ 和 @@ 别名，相对于其 layer 的 source 和 root 目录进行解析。此标志默认启用，但您可以禁用此功能：

typedPages

启用新的实验性类型化路由器。开箱即用，这将为 navigateTo、<NuxtLink>、router.push() 等提供类型支持。您甚至可以通过在页面中使用 const route = useRoute('route-name') 来获得类型化的 params。

watcher

设置将用作 Nuxt 监视服务的替代 watcher。Nuxt 默认使用 chokidar-granular，它会忽略被排除在监视之外的顶级目录（例如 node_modules 和 .git）。您可以将其设置为 parcel 以使用 @parcel/watcher，这在大型项目或 Windows 平台上可能会提高性能。您也可以将其设置为 chokidar 来监视源目录中的所有文件。将其设置为 'builder' 可重用当前构建器自己的文件监视器（例如 Vite 的 server.watcher），而不是再启动一个监视器。这会减少开发模式下活动的文件监视器数量，并且在 future.compatibilityVersion 为 5 时会成为默认值。如果当前构建器没有实现自己的监视器（目前是 webpack 和 rspack），Nuxt 会记录警告并回退到默认选择。

sharedPrerenderData

Nuxt 会自动在预渲染的页面之间共享 payload data。当预渲染使用 useAsyncData 或 useFetch，并且在不同页面中获取相同数据时，这可以显著提高性能。如果需要，您可以禁用此功能。启用此功能时，确保数据的任何唯一键始终解析为相同的数据非常重要。例如，如果您在动态页面中使用 useAsyncData 来获取与特定页面相关的数据，则应提供一个唯一对应于该数据的键。（useFetch 应会自动为您完成这一步。）

clientNodeCompat

启用此功能后，Nuxt 将在客户端构建中使用 unenv 自动为 Node.js 导入提供 polyfill。

scanPageMeta

Nuxt 在构建时向模块公开在 definePageMeta 中定义的一些路由元数据（特别是 alias、name、path、redirect、props 和 middleware）。这仅适用于静态值或字符串/数组，而不适用于变量或条件赋值。有关更多信息和上下文，请参阅原始问题。默认情况下，页面元数据仅在 pages:extend 中所有路由注册完成后才会被扫描。然后会调用另一个钩子 pages:resolved。如果此功能在您的项目中造成问题，您可以禁用它。

cookieStore

启用 CookieStore 支持以监听 cookie 更新（如果浏览器支持）并刷新 useCookie 的 ref 值。此标志默认启用，但您可以禁用此功能：

buildCache

基于配置和源文件的哈希缓存 Nuxt 构建产物。这仅适用于 srcDir 和 serverDir 中的源文件，用于您应用的 Vue/Nitro 部分。此标志默认禁用，但您可以启用它：启用后，以下文件的更改将触发完全重建：此外，srcDir 中任何文件的更改都将触发 Vue 客户端/服务端包的重建。Nitro 将始终被重建（不过目前正在进行相关工作，以允许 Nitro 声明其可缓存的产物及其哈希）。

checkOutdatedBuildInterval

设置检查新构建的时间间隔（以毫秒为单位）。当 experimental.appManifest 为 false 时此功能被禁用。设置为 false 可禁用该检查。

extraPageMetaExtractionKeys

definePageMeta() 宏是收集页面构建时元数据的有用方式。Nuxt 本身提供了一组受支持的键列表，用于驱动一些内部功能，例如重定向、页面别名和自定义路径。此选项允许在使用 scanPageMeta 时传入额外的键以从页面元数据中提取。这允许模块在构建上下文中访问页面元数据中的额外元信息。如果您在模块中使用此功能，建议也通过您的键扩展 NuxtPage 类型。

extractSerializablePageMeta

当 future.compatibilityVersion 为 5 或更高版本时默认启用。默认情况下，Nuxt 只会在构建时读取固定列表中的 definePageMeta() 键（以及 extraPageMetaExtractionKeys 中的任何内容）；其他所有内容都会在运行时从为每个页面单独生成的模块中解析。启用此选项后，Nuxt 会直接将每个可序列化为 JSON 的属性写入生成的路由记录中。当页面的 definePageMeta() 中的所有属性都可以静态解析时，路由将完全不再导入该页面的元数据模块，从而使开发环境模块图中每个页面减少一个模块。值无法序列化的属性（函数、变量引用、展开运算符、计算属性键）不受影响，仍会在运行时解析。当 scanPageMeta 为 false 时，此选项不会生效，因为此时路由记录不会覆盖元数据模块。

navigationRepaint

在导航前等待一个动画帧，使浏览器有机会重绘以响应用户交互。在导航到预渲染路由时，这可以减少 INP。此标志默认启用，但您可以禁用此功能：

navigateToEarlyReturn

将 <script setup> 中顶层的 await navigateTo() 调用转换为已编译 setup() 函数中的提前返回，此操作仅在导航成功时发生。不启用此标志时，await navigateTo() 后的代码会继续运行，这可能导致后续代码（包括后续的 navigateTo 调用）覆盖重定向，或尝试渲染缺少数据的页面。启用此标志后，成功的导航会停止执行其余 setup 代码，并且组件会在导航继续进行时渲染一个占位符注释。此标志在 compatibilityVersion: 5 下默认启用，但您可以禁用它：此转换仅适用于 <script setup> 中未使用其结果的顶层 await navigateTo() 语句。带有 open 选项的调用（或无法进行静态分析的选项）不会被转换，因为它们不应阻止当前页面渲染。只有在导航成功时才会提前返回（也就是说，当 navigateTo 解析为 undefined 时）。如果导航被中止或失败（例如被导航守卫阻止，或导航到当前路由），其余 setup 代码会继续运行。导航成功后，navigateTo 调用之后的任何内容都不会运行，包括 defineExpose 以及 <script setup> 中之后注册的任何生命周期钩子。

normalizeComponentNames

Nuxt 更新自动生成的 Vue 组件名称，以匹配用于自动导入组件时的完整组件名。如果遇到问题，您可以禁用此功能。默认情况下，如果您没有手动设置，Vue 会为组件分配与组件文件名匹配的名称。在这种情况下，Vue 认为组件名是 MyComponent。如果您想对它使用 <KeepAlive>，或在 Vue DevTools 中识别它，您需要使用该组件名。但为了自动导入它，您需要使用 SomeFolderMyComponent。通过设置 experimental.normalizeComponentNames，这两个值将匹配，Vue 将生成与 Nuxt 组件命名模式一致的组件名称。

normalizePageNames

确保页面组件名称与其路由名称匹配。此功能会在页面组件上设置 __name 属性，使 Vue 的 <KeepAlive> 能通过名称正确识别它们。默认情况下，Vue 根据文件名分配组件名称。例如，pages/foo/index.vue 和 pages/bar/index.vue 都会被命名为 index。这种情况让基于名称的 <KeepAlive> 过滤变得不可靠，因为多个页面共享相同的名称。开启 normalizePageNames 后，页面组件将以路由名称命名（例如 foo 和 bar），这样您就可以使用 <KeepAlive> 的 include/exclude 功能，而不用为每个页面手动添加 defineOptions({ name: '...' })。当 future.compatibilityVersion 设置为 5 或更高时，此标志默认启用，但您可以禁用该功能：

spaLoadingTemplateLocation

在渲染仅客户端页面（ssr: false）时，可选地渲染一个加载屏幕（来自 ~/spa-loading-template.html）。可以将其设置为 within，将按如下方式渲染：或者，您可以通过将其设置为 body 将模板与 Nuxt 应用根并列渲染：这可以避免在为仅客户端页面执行水合时出现白屏闪烁。

browserDevtoolsTiming

为浏览器开发者工具启用 Nuxt 钩子的性能标记（performance markers）。这会在基于 Chromium 的浏览器的性能选项卡中添加可跟踪的性能标记，便于调试和优化性能。在开发模式下默认启用此功能。如果需要禁用，可以这样做：

debugModuleMutation

记录模块上下文中对 nuxt.options 的变更，以帮助调试 Nuxt 初始化阶段模块所做的配置更改。当启用 debug 模式时默认启用此功能。如果需要禁用，也可以这样做：要显式启用它：

lazyHydration

为 <Lazy> 组件启用延迟水合（hydration）策略，通过延迟组件的水合来提高性能。默认启用延迟水合，但您可以禁用此功能：

templateImportResolution

禁用从添加模板的模块的路径解析 Nuxt 模板中的导入。默认情况下，Nuxt 会尝试将模板中的导入相对于添加它们的模块进行解析。将此设置为 false 会禁用该行为，这在某些环境中遇到解析冲突时可能有用。此标志默认启用，但您可以禁用此功能：

templateRouteInjection

默认情况下，自动导入的 useRoute() composable 返回的路由对象会与 <NuxtPage> 中当前可见页面保持同步。对于 vue-router 导出的 useRoute 或 Vue 模板中可用的默认 $route 对象则不然。启用此选项将注入一个 mixin，以使模板中的 $route 对象与 Nuxt 管理的 useRoute() 保持同步。此标志默认启用，但您可以禁用此功能：

装饰器

此选项启用在整个 Nuxt/Nitro 应用中使用装饰器语法（decorator syntax），由 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 实现。

使用示例

当使用 Vite 构建器（默认）时，装饰器通过 Babel 及其 @babel/plugin-proposal-decorators 插件来转译。使用 webpack 或 rspack 构建器时，装饰器通过 esbuild 进行转译。当使用 Vite 构建器或 Nitro 服务器构建时，您需要安装额外的 Babel 包作为开发依赖：

默认值

此项允许为核心 Nuxt 组件和 composable 指定默认选项。这些选项今后可能会被移到其他地方，例如 app.config 或 app/ 目录中。useState.resetOnClear 选项控制 clearNuxtState 是否将状态重置为初始值（由 useState 的 init 函数提供），而不是将状态设置为 undefined。在 compatibilityVersion: 5 下默认值为 true。

purgeCachedData

是否在路由导航时清理 Nuxt 的静态和 asyncData 缓存。Nuxt 将自动清除 useAsyncData 和 nuxtApp.static.data 的缓存数据。这有助于防止内存泄漏并确保在需要时加载最新数据，但您也可以禁用此功能。此标志默认启用，但您可以禁用此功能：

prefetchPreloadTags

当预取 <NuxtLink> 且目标路由启用了 负载提取（预渲染和缓存路由的默认设置）时，会将目标通过 useHead（或通过 @nuxt/image 的 <NuxtImg preload> 等模块）设置的任何 <link rel="preload"> 提示转发到当前文档中。转发的链接会从 rel="preload" 降级为 rel="prefetch"，因此它们不会与当前页面的关键资源竞争。只有用户定义的 head 标签会被转发；构建时的 JS/CSS chunk preload 已由预取管线单独处理。此标志默认关闭，因为它与 prefetchOn: 'visibility'（<NuxtLink> 的默认值）结合时，可能会一次性触发大量跨路由预取。只有当您确信目标预加载值得为用户通常遇到的链接进行转发时，再启用它。

granularCachedData

在刷新 useAsyncData 和 useFetch 的数据时（无论是由 watch、refreshNuxtData() 还是手动调用 refresh() 触发），是否调用并使用 getCachedData 的结果。此标志默认启用，但您可以禁用此功能：

stripNeverHydratedData

默认将 serialize: false 应用于在使用 hydrate-never 惰性 hydration 的组件内发起的 useAsyncData 和 useFetch 调用，以将它们的数据排除在 __NUXT_DATA__ 负载之外。由于这些组件在客户端上永远不会进行 hydration，因此它们的数据不需要用于 hydration。显式的 serialize 选项始终具有优先级。如果相同的 key 与会进行 hydration 的组件共享，请在各次调用中保持 serialize 选项一致（Nuxt 会在开发环境中对不匹配发出警告）。

headNext

使用头部优化：

• 添加 capo.js head 插件，以更高效地渲染 head 中的标签。
• 使用 hash hydration 插件以减少初始水合。

此标志默认启用，但您可以禁用此功能：

pendingWhenIdle

pendingWhenIdle 控制 useAsyncData 和 useFetch 返回的 pending ref。当 pendingWhenIdle 为 false（默认值）时，pending 在请求进行中时为 true，并且与 status === 'pending' 匹配。当 status 为 idle 时，pending 保持为 false。你可以通过 { immediate: false }，或者在服务端渲染期间使用 { server: false } 看到这一点。将 pendingWhenIdle 设置为 true，这样当 status 为 idle 且没有可用的缓存数据时，pending 也会为 true。当你的加载界面需要区分 idle 和正在进行中的请求时，请使用 status。

entryImportMap

默认情况下，Nuxt 通过使用导入映射（import map）来解析 bundle 的入口 chunk，从而提高 chunk 的稳定性。这会在 <head> 标签顶部注入一个导入映射：在 Vite 发出的脚本 chunk 中，导入将来自 #entry。这意味着入口的更改不会使那些未改变的 chunk 失效。如果需要禁用该功能，您可以这样做：

typescriptPlugin

启用 @dxup/nuxt 模块的增强 TypeScript 开发体验。这个实验性插件为在 Nuxt 应用中使用 TypeScript 提供了更好的集成和开发工具，以改善开发体验。此标志默认情况下是禁用的，但您可以启用此功能：

ssrStreaming

启用 SSR 流式传输，以显著提升首字节时间（TTFB）。启用后，服务器会立即发送 HTML 外壳（包括 <head>、样式、预加载提示和入口脚本），然后使用 Vue 的 renderToWebStream 逐步流式传输渲染后的主体内容。对于 bot 和爬虫用户代理（例如 Googlebot、Bingbot 等），会自动禁用流式传输，以确保搜索引擎接收到完整渲染的 HTML，保证 SEO 安全。默认模式仅匹配索引爬虫；Lighthouse 和其他审计工具会刻意排除在外，因此合成测量反映的是与真实用户相同的流式响应。您可以自定义 bot 检测正则：您还可以使用 routeRules 按路由控制流式传输：

模块钩子

模块通过现有的 render:html 钩子参与流式响应（现在第二个参数上带有 streaming: true 标志），外加一个按请求决策钩子和两个仅用于流式传输的钩子：

• render:route 在每次请求、每次渲染开始前触发（无论是否启用流式传输）。读取 ctx.canStream 可查看该路由是否可以流式传输，并设置 ctx.prefersStream = false 以强制本次请求使用缓冲渲染，例如基于 cookie、认证状态或 A/B 分组。只有当 canStream && prefersStream 时，渲染器才会进行流式传输。这是针对静态 routeRules / botRegex 配置的运行时逃生口。
• render:html 在外壳刷新之前触发一次，且其第二个参数上带有 streaming: true。对 htmlAttrs、head、bodyAttrs 和 bodyPrepend 的修改会传递到网络响应中。对 body/bodyAppend 的修改会被丢弃，因为主体即将开始流式传输（开发模式下会发出警告）。仅修改 head 字段的模块（CSP 注入、OG 标签、分析元数据）无需改动代码即可在流式传输中工作。
• render:html:chunk 在渲染器生成每个 chunk 并将其入队前触发。修改 ctx.chunk: Uint8Array 以转换字节（例如注入 nonce）；读取 ctx.index 以识别第一个 chunk 与后续 chunk。
• render:html:close 在主体流完成后、闭合标签之前触发。修改 ctx.bodyAppend: string[] 以注入最终标记（body 末尾的分析标签、服务端渲染的调试小部件等）。