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

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

asyncContext

启用原生异步上下文，以便在 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

从服务器包中摇树去除仅客户端组件的内容。

默认启用。

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

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

为了避免水合错误，它将在 Vue 应用程序挂载后才应用，这意味着在初始加载时可能会出现闪烁。

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

启用与客户端路由器的视图过渡 API 集成。

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

writeEarlyHints

在使用节点服务器时启用早期提示的写入。

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') 在页面内获取类型化参数。

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 会影响获取的数据，但 Nuxt 无法知道这一点，因为它没有反映在键中。
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 导入。

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer

scanPageMeta

此选项允许在构建时将 definePageMeta 中定义的一些路由元数据暴露给模块（特别是 alias、name、path、redirect、props 和 middleware）。

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

在所有路由在 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.lock
bun.lockb

此外，对 srcDir 中文件的任何更改将触发 Vue 客户端/服务器包的重建。Nitro 将始终被重建（尽管正在进行工作以允许 Nitro 宣布其可缓存的工件及其哈希）。

extraPageMetaExtractionKeys

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

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

definePageMeta({
  foo: 'bar'
})

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 加载模板 -->
</div>

或者，您可以通过将其设置为 body 来在 Nuxt 应用程序根目录旁边渲染模板：

<div id="__nuxt"></div>
<!-- spa 加载模板 -->

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

browserDevtoolsTiming

在浏览器开发工具中启用 Nuxt 钩子的性能标记。这会添加性能标记，您可以在基于 Chromium 的浏览器的性能选项卡中跟踪这些标记，这对于调试和优化性能非常有用。

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

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

此选项启用整个 Nuxt/Nitro 应用程序中的装饰器语法，由 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,
  },
})

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 也处于挂起状态时为 true。

这意味着当传递 immediate: false 时，pending 将在第一次请求发出之前为 false。

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