实验性特性

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

在内部，Nuxt 使用 @nuxt/schema 来定义这些实验性特性。你可以参考 API 文档 或源代码 了解更多信息。

alwaysRunFetchOnKeyChange

是否在 key 改变时运行 useFetch，即使它被设置为 immediate: false 且尚未被触发。

如果 immediate: true 或它已经被触发过，useFetch 和 useAsyncData 在 key 改变时总是会运行。

这个标志默认是禁用的，但你可以启用此特性：

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

appManifest

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

这个标志默认是启用的，但你可以禁用此特性：

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

asyncContext

启用原生 async 上下文，使其在 Nuxt 和 Nitro 中的嵌套组合式函数中可访问。这为在 async 组合式函数内部使用组合式函数打开了可能性，并减少了遇到 Nuxt instance is unavailable（Nuxt 实例不可用）错误的机会。

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

asyncEntry

为 Vue bundle 生成异步入口点，辅助模块联邦支持。

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

extractAsyncDataHandlers

从 useAsyncData 和 useLazyAsyncData 调用中提取处理函数到独立的 chunk 中，以改善代码分割和缓存效率。

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

此特性将内联的处理函数转换为动态导入的 chunk：

<!-- 转换前 -->
<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 加载失败时执行新路由的重新加载。

默认情况下，当导航到新路由时某个 chunk 加载失败，Nuxt 也会执行新路由的重新加载（automatic 自动）。

设置为 automatic-immediate 会让 Nuxt 在 chunk 加载失败时立即执行当前路由的重新加载（而不是等待导航）。这对于非由导航触发的 chunk 错误很有用，例如当你的 Nuxt 应用未能加载某个懒加载组件 时。这种行为的一个潜在缺点是产生不期望的重新加载，例如当你的应用并不需要导致错误的那个 chunk 时。

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

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

enforceModuleCompatibility

当某个 Nuxt 模块不兼容时，Nuxt 是否应抛出错误（并加载失败）。

此特性默认是禁用的。

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

restoreState

在 chunk 错误或手动调用 reloadNuxtApp() 后重新加载页面时，允许从 sessionStorage 恢复 Nuxt 应用状态。

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

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

inlineRouteRules

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

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

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

noVueServer

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

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

parseErrorData

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

这个标志默认是启用的，但你可以禁用此特性：

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

payloadExtraction

控制预渲染和缓存（ISR/SWR）页面的 payload 数据如何传递。

• 'client' - payload 在初始服务端渲染时内联在 HTML 中，并为客户端导航提取到 _payload.json 文件。
• true - payload 提取为单独的 _payload.json 文件，用于初始服务端渲染和客户端导航。
• false - 完全禁用 payload 提取。payload 始终内联在 HTML 中，不会生成任何 _payload.json 文件。

默认值为 true，或者在设置了 compatibilityVersion: 5 时为 'client'。当设置了 ssr: false 时，它会被强制设为 false。

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

clientNodePlaceholder

在服务端渲染期间，使用注释节点（<!--placeholder-->）代替 <div> 元素作为仅客户端组件的占位符。

启用后，.client.vue 组件和 createClientOnly() 包装器会在服务端渲染一个 HTML 注释，而不是一个空的 <div>。这修复了一个 Vue 水合问题：当占位 <div> 与实际组件的根元素共享相同的标签名时，作用域样式可能不会被应用。

当 future.compatibilityVersion 设置为 5 或更高时，此标志默认启用，但你也可以显式启用它：

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

clientFallback

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

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

crossOriginPrefetch

使用 Speculation Rules API 启用跨域预取。

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 server 时启用 early hints 的写入。

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

componentIslands

启用实验性的组件 islands 支持，配合 <NuxtIsland> 和 .island.vue 文件。

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

localLayerAliases

解析位于 layers 内部的 ~、~~、@ 和 @@ 别名，参照它们的 layer 源目录和根目录。

这个标志默认是启用的，但你可以禁用此特性：

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

typedPages

启用新的实验性类型化路由。

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

开箱即用，这将启用 navigateTo、<NuxtLink>、router.push() 等的类型化用法，以及更多。

你甚至可以通过使用 const route = useRoute('route-name') 在页面内获得类型化的参数。