实验性功能

启用 Nuxt 实验性功能，解锁更多可能。

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

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

请注意，这些功能是实验性的，将来可能会被移除或修改。

alwaysRunFetchOnKeyChange

是否在 key 变化时运行 useFetch，即使设置了 immediate: false 且尚未触发。

当 immediate: true 或已触发时，useFetch 与 useAsyncData 总会在 key 变化时运行。

该标志默认禁用，但你可以启用该功能：

nuxt.config.ts

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

appManifest

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

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

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: false,
  },
})

该功能可能在不久的将来被移除。

extractAsyncDataHandlers

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

nuxt.config.ts

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 分块失败时，触发 app:chunkError 钩子。默认行为是在导航到新路由时，若分块加载失败则刷新新路由。

若设置为 'automatic-immediate'，则 Nuxt 会立即刷新当前路由，而不是等待导航。这对于非导航触发的分块错误（例如，Nuxt 应用加载懒组件失败）非常有用。但此行为可能导致不必要的刷新，例如应用不需要导致错误分块时。

可以通过设置为 false 禁用自动处理，或设置为 manual 手动处理分块错误。

nuxt.config.ts

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

enforceModuleCompatibility

是否在 Nuxt 模块不兼容时抛出错误（并阻止加载）。

该功能默认禁用。

nuxt.config.ts

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

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 工具。

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

renderJsonPayloads

允许渲染包含复杂类型复活支持的 JSON 负载。

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

noVueServer

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

nuxt.config.ts

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

parseErrorData

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

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

payloadExtraction

启用提取使用 nuxt generate 生成页面的负载。

nuxt.config.ts

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

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

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
  routeRules: {
    // 将为这些缓存路由生成负载文件
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: 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'
  },
})

在 Docs > 3 X > Directory Structure > Components#server Components 中查看详情

你可以在 GitHub 上关注服务器组件的路线图。

localLayerAliases

解析位于层内的 ~、~~、@ 和 @@ 别名，基于其层源和根目录。

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

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: false,
  },
})

启用该功能时，确保任何数据的唯一键始终指向相同数据非常重要。例如，若使用 useAsyncData 获取特定页面的数据，应提供唯一匹配该数据的键。（useFetch 会自动处理这点。）

// 在动态页面（如 `[slug].vue`）中，若未将路由 slug 反映到键中，则不安全。
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// 正确做法是为数据提供唯一标识符的键。
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。

若需在浏览器端使用全局变量如 Buffer，需手动注入：

import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer

scanPageMeta

允许在构建时向模块暴露通过 definePageMeta 定义的部分路由元数据（具体包含 alias、name、path、redirect、props 和 middleware）。

仅支持静态值或字符串/数组，不支持变量或条件赋值。详情见原始 Issue。

默认情况下，页面元数据仅在所有路由通过 pages:extend 注册后扫描，随后会触发钩子 pages:resolved。

若该功能引发问题，亦可禁用。

nuxt.config.ts

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

cookieStore

启用 CookieStore 支持，监听浏览器 Cookie 更新（如果浏览器支持），并刷新 useCookie 的响应式值。

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

阅读更多关于 CookieStore。

buildCache

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

仅对 srcDir 和 serverDir 中用于 Vue/Nitro 应用的源码文件有效。

该标志默认禁用，但你可以启用：

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 个缓存压缩包。

checkOutdatedBuildInterval

设置检测新构建的时间间隔（毫秒）。当 experimental.appManifest 为 false 时禁用。

设置为 false 可禁用此功能。

nuxt.config.ts

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（交互到完成延迟）。

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

nuxt.config.ts

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

normalizeComponentNames

Nuxt 更新自动生成的 Vue 组件名，使其与用于自动导入组件时的完整组件名一致。

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

nuxt.config.ts

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

默认情况下，若未手动设置，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 的实现细节。

templateRouteInjection

默认情况下，自动导入的 useRoute() 组合函数返回的路由对象保持与 <NuxtPage> 中当前页面同步。这不适用于 vue-router 导出的 useRoute 或 Vue 模板中的默认 $route 对象。

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

该标志默认启用，但你可以禁用该功能：

nuxt.config.ts

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

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'

defaults

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

这些选项将来可能迁移到其他位置，比如 app.config 或 app/ 目录。

nuxt.config.ts

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

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: false,
  },
})

查看 PR #31373 的实现细节。

headNext

使用头标签优化：

添加 capo.js 头插件，以更高效地渲染头标签中的内容。
使用哈希水合插件减少初始水合工作。

该标志默认启用，但你可以禁用：

nuxt.config.ts

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

pendingWhenIdle

对于 useAsyncData 和 useFetch，是否在数据尚未开始获取时将 pending 设为 true。

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

nuxt.config.ts

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

entryImportMap

默认情况下，Nuxt 通过使用导入映射（import map）来提升代码块的稳定性，从而解析打包的入口代码块。

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

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

在 Vite 输出的脚本代码块中，引入会从 #entry 开始。这意味着入口文件的变更不会使其他未变更的代码块失效。

当你配置了 vite.build.target 包含不支持导入映射的浏览器，或配置了不含 [hash] 的 vite.build.rollupOptions.output.entryFileNames 时，Nuxt 会智能禁用此功能。

如果需要禁用此功能，可以这样设置：

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // 或者，最好是直接告诉 vite 你想要的目标环境
  // Nuxt 会尊重该配置
  vite: {
    build: {
      target: 'safari13',
    },
  },
})

typescriptPlugin

启用使用 @dxup/nuxt 模块，提升 TypeScript 开发体验。

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

默认禁用，你可以启用：

nuxt.config.ts

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

使用此功能需要：

安装 typescript 作为依赖
将 VS Code 配置为使用工作区的 TypeScript 版本（参见 VS Code 文档）

了解更多 @dxup/nuxt。

viteEnvironmentApi

启用 Vite 6 新的环境 API，以改善构建配置和插件架构。

当你将 future.compatibilityVersion 设为 5 时，该功能默认启用，也可显式开启用于测试：

nuxt.config.ts

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

Vite 环境 API 提供更一致的开发和生产构建体验，更细粒度的环境相关配置控制，以及更好的性能。

启用此功能会改变 Vite 插件的注册和配置方式。详见 Vite 环境 API 迁移指南了解插件更新细节。

了解更多 Vite 环境 API。

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

自定义事件

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

功能

启用或禁用可选的 Nuxt 功能，解锁更多可能性。