实验特性

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

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

alwaysRunFetchOnKeyChange

当 key 发生变化时，是否运行 useFetch，即便其设置为 immediate: false 且尚未被触发。

如果 immediate: true 或已被触发，useFetch 和 useAsyncData 在 key 更改时将始终运行。

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

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

appManifest

使用应用清单以在客户端遵循路由规则。

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

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

asyncContext

启用原生异步上下文，使其可在 Nuxt 和 Nitro 中被嵌套的 composable 访问。这使得在异步 composable 中使用 composable 成为可能，并减少出现 Nuxt instance is unavailable 错误的概率。

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

asyncEntry

为 Vue 包生成异步入口点，以利于模块联邦（module federation）的支持。

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

externalVue

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

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

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

extractAsyncDataHandlers

从 useAsyncData 和 useLazyAsyncData 调用中提取处理函数到单独的块，以提高代码拆分和缓存效率。

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>

这种转变的好处在于，我们可以将数据获取逻辑分离出来，同时仍然允许在需要时加载代码。

emitRouteChunkError

在加载 vite/webpack chunk 时发生错误时发出 app:chunkError 钩子。默认行为是在导航到新路由时，当 chunk 无法加载时重新加载新路由。

默认情况下，Nuxt 在导航到新路由时，如果 chunk 无法加载也会执行路由重载（automatic）。

设置为 automatic-immediate 将使 Nuxt 在 chunk 无法加载时立即对当前路由执行重载（而不是等待导航）。这对非导航触发的 chunk 错误很有用，例如当 Nuxt 应用无法加载懒加载组件。这种行为的一个潜在缺点是可能会导致不希望的重载，例如当应用并不需要导致错误的那部分 chunk 时。

您可以将其设置为 false 来禁用自动处理，或设置为 manual 以手动处理 chunk 错误。

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

enforceModuleCompatibility

当 Nuxt 模块不兼容时，是否应抛出错误并阻止加载。

此功能默认禁用。

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

restoreState

允许在发生 chunk 错误或手动调用 reloadNuxtApp() 后，从 sessionStorage 恢复 Nuxt 应用状态。

为了避免水合（hydration）错误，此操作仅在 Vue 应用挂载后应用，这意味着初次加载时可能会有闪烁现象。

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

inlineRouteRules

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

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

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

renderJsonPayloads

允许以支持复活（revivifying）复杂类型的方式渲染 JSON payload。

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

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

noVueServer

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

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

parseErrorData

在渲染服务器错误页面时是否解析 error.data。

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

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

payloadExtraction

Controls how payload data is delivered for prerendered and cached (ISR/SWR) pages.

• 'client' - Payload is inlined in HTML for the initial server render, and extracted to _payload.json files for client-side navigation. This avoids a separate network request on initial load while still enabling efficient client-side navigation.
• true - Payload is extracted to a separate _payload.json file for both the initial server render and client-side navigation.
• false - Payload extraction is disabled entirely. Payload is always inlined in HTML and no _payload.json files are generated.

The default is true, or 'client' when compatibilityVersion: 5 is set.

export default defineNuxtConfig({
  experimental: {
    // Inline payload in HTML, extract for client-side navigation only
    payloadExtraction: 'client',
  },
})

Payload 提取同样适用于使用 ISR（增量静态再生成）或 SWR（陈旧-重新验证）缓存策略的路由。这允许 CDN 将 payload 文件与 HTML 一起缓存，以提升缓存路由的客户端导航性能。

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: 'client',
  },
  routeRules: {
    // 将为这些缓存路由生成 payload 文件
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: true },
  },
})

clientFallback

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

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

crossOriginPrefetch

使用 Speculation Rules API 启用跨域预取（cross-origin prefetch）。

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

viewTransition

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

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

您也可以传入一个对象来配置 视图过渡类型，它允许基于导航类型使用不同的 CSS 动画：

export default defineNuxtConfig({
  experimental: {
    viewTransition: {
      enabled: true,
      types: ['slide'],
    },
  },
})

writeEarlyHints

在使用 Node 服务器时启用写入 early hints。

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

componentIslands

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

export default defineNuxtConfig({
  experimental: {
    componentIslands: true, // 也可为 false 或 'local+remote'
  },
})

localLayerAliases

解析位于 layer 内的 ~、~~、@ 和 @@ 别名，相对于其 layer 的 source 和 root 目录进行解析。

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

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

typedPages

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

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

开箱即用，这将为 navigateTo、<NuxtLink>、router.push() 等提供类型支持。

您甚至可以通过在页面中使用 const route = useRoute('route-name') 来获得类型化的 params。

publicHoistPattern:
  - "unplugin-vue-router"

watcher

设置将用作 Nuxt 监视服务的替代 watcher。

Nuxt 默认使用 chokidar-granular，它会忽略被排除在监视之外的顶级目录（例如 node_modules 和 .git）。

您可以将其设置为 parcel 以使用 @parcel/watcher，这在大型项目或 Windows 平台上可能会提高性能。

您也可以将其设置为 chokidar 来监视源目录中的所有文件。

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular', // 也可为 'chokidar' 或 'parcel'
  },
})

sharedPrerenderData

Nuxt 自动在预渲染的页面之间共享 payload data。当预渲染使用 useAsyncData 或 useFetch 且在不同页面中获取相同数据时，这可以显著提高性能。

如果需要，您可以禁用此功能。

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

启用此功能时特别重要的是确保您的数据的任何唯一键总是可解析为相同的数据。例如，如果您在动态页面中使用 useAsyncData 来获取与特定页面相关的数据，则应提供一个唯一匹配该数据的键。（useFetch 应会为您自动做到这一点。）

// 这在动态页面（例如 `[slug].vue`）中不安全，因为路由 slug 会影响获取的数据
// 但 Nuxt 因为不反映在 key 中，因此无法识别差异。
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// 相反，您应使用一个唯一标识所获取数据的 key。
const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})

clientNodeCompat

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

import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer

scanPageMeta

Nuxt 在构建时向模块公开在 definePageMeta 中定义的一些路由元数据（特别是 alias、name、path、redirect、props 和 middleware）。

这仅适用于静态值或字符串/数组，而不适用于变量或条件赋值。有关更多信息和上下文，请参阅原始问题。

默认情况下，页面元数据仅在 pages:extend 中所有路由注册完成后才会被扫描。然后会调用另一个钩子 pages:resolved。

如果此功能在您的项目中造成问题，您可以禁用它。

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

cookieStore

启用 CookieStore 支持以监听 cookie 更新（如果浏览器支持）并刷新 useCookie 的 ref 值。

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

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

buildCache

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

这仅适用于 srcDir 和 serverDir 中的源文件，用于您应用的 Vue/Nitro 部分。

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

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 宣告其可缓存的产物及其哈希）。

checkOutdatedBuildInterval

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

设置为 false 可禁用该检查。

export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 小时，或 false 表示禁用
  },
})

extraPageMetaExtractionKeys

definePageMeta() 宏是收集页面构建时元数据的有用方式。Nuxt 本身提供了一组受支持的键列表，用于驱动一些内部功能，例如重定向、页面别名和自定义路径。

此选项允许在使用 scanPageMeta 时传入额外的键以从页面元数据中提取。

<script lang="ts" setup>
definePageMeta({
  foo: 'bar',
})
</script>

export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ 现在可以访问 foo
    },
  },
})

这允许模块在构建上下文中访问页面元数据中的额外元信息。如果您在模块中使用此功能，建议也通过您的键扩展 NuxtPage 类型。

navigationRepaint

在导航前等待一个动画帧，使浏览器有机会重绘以响应用户交互。

在导航到预渲染路由时，这可以减少 INP。

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

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

normalizeComponentNames

Nuxt 更新自动生成的 Vue 组件名称，以匹配用于自动导入组件时的完整组件名。

如果遇到问题，您可以禁用此功能。

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

默认情况下，如果您没有手动设置，Vue 会为组件分配与组件文件名匹配的名称。

├─ components/
├─── SomeFolder/
├───── MyComponent.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 或更高时，此标志默认启用，但您可以禁用该功能：

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

<template>
  <NuxtPage :keepalive="{ include: ['foo'] }" />
</template>

spaLoadingTemplateLocation

在渲染仅客户端页面（ssr: false）时，可选地渲染一个加载屏幕（来自 ~/spa-loading-template.html）。

可以将其设置为 within，将按如下方式渲染：

<div id="__nuxt">
  <!-- spa loading template -->
</div>

或者，您可以通过将其设置为 body 将模板与 Nuxt 应用根并列渲染：

<div id="__nuxt"></div>
<!-- spa loading template -->

这可以避免在为仅客户端页面执行水合时出现白屏闪烁。

browserDevtoolsTiming

为浏览器开发者工具启用 Nuxt 钩子的性能标记（performance markers）。这会在基于 Chromium 的浏览器的 Performance 选项卡中添加可跟踪的性能标记，便于调试和优化性能。

在开发模式下默认启用此功能。如果需要禁用，可以这样做：

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

debugModuleMutation

记录模块上下文中对 nuxt.options 的变更，以帮助调试 Nuxt 初始化阶段模块所做的配置更改。

当启用 debug 模式时默认启用此功能。如果需要禁用，也可以这样做：

要显式启用它：

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

lazyHydration

为 <Lazy> 组件启用延迟水合（hydration）策略，通过延迟组件的水合来提高性能。

默认启用 lazy hydration，但您可以禁用此功能：

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

templateImportResolution

禁用从添加模板的模块的路径解析 Nuxt 模板中的导入。

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

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

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

templateRouteInjection

默认情况下，自动导入的 useRoute() composable 返回的路由对象会与 <NuxtPage> 中当前可见页面保持同步。对于 vue-router 导出的 useRoute 或 Vue 模板中可用的默认 $route 对象则不然。

启用此选项将注入一个 mixin，以使模板中的 $route 对象与 Nuxt 管理的 useRoute() 保持同步。

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

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

decorators

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

用法示例

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

当使用 Vite 构建器（默认）时，装饰器通过 Babel 及其 @babel/plugin-proposal-decorators 插件来转译。使用 webpack 或 rspack 构建器时，装饰器通过 esbuild 进行转译。

当使用 Vite 构建器或 Nitro 服务器构建时，您需要安装额外的 Babel 包作为开发依赖：

npm install -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx

pnpm add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx

yarn add -D @babel/plugin-proposal-decorators @babel/plugin-syntax-jsx

function something (_method: () => unknown) {
  return () => 'decorated'
}

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

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

defaults

此项允许为核心 Nuxt 组件和 composable 指定默认选项。

这些选项今后可能会被移到其他地方，例如 app.config 或 app/ 目录中。

export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        componentName: 'NuxtLink',
        prefetch: true,
        prefetchOn: {
          visibility: true,
        },
      },
      useAsyncData: {
        deep: true,
      },
      useState: {
        resetOnClear: true,
      },
    },
  },
})

useState.resetOnClear 选项控制 clearNuxtState 是否将状态重置为初始值（由 useState 的 init 函数提供），而不是将状态设置为 undefined。在 compatibilityVersion: 5 下默认值为 true。

purgeCachedData

是否在路由导航时清理 Nuxt 的静态和 asyncData 缓存。

Nuxt 将自动清除 useAsyncData 和 nuxtApp.static.data 的缓存数据。这有助于防止内存泄漏并确保在需要时加载最新数据，但您也可以禁用此功能。

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

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

granularCachedData

在刷新 useAsyncData 和 useFetch 的数据时（无论是由 watch、refreshNuxtData() 还是手动调用 refresh() 触发），是否调用并使用 getCachedData 的结果。

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

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

headNext

使用头部优化：

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

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

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

pendingWhenIdle

对于 useAsyncData 和 useFetch，当数据尚未开始被获取时，pending 是否应为 true。

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

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

entryImportMap

默认情况下，Nuxt 通过使用导入映射（import map）来解析 bundle 的入口 chunk，从而提高 chunk 的稳定性。

这会在 <head> 标签顶部注入一个导入映射：

<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>

在 Vite 发出的脚本 chunk 中，导入将来自 #entry。这意味着入口的更改不会使那些未改变的 chunk 失效。

如果需要禁用该功能，您可以这样做：

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // 或者，更好地告诉 vite 您的期望目标
  // Nuxt 将尊重此配置
  vite: {
    build: {
      target: 'safari13',
    },
  },
})

typescriptPlugin

启用 @dxup/nuxt 模块的增强 TypeScript 开发体验。

这个实验性插件为在 Nuxt 应用中使用 TypeScript 提供了更好的集成和开发工具，以改善开发体验。

此标志默认情况下是禁用的，但您可以启用此功能：

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