实验性功能

启用 Nuxt 实验性功能以解锁新的可能性。

Nuxt 包含一些实验性功能，你可以在配置文件中启用它们。

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

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

asyncContext

启用原生异步上下文，使 Nuxt 和 Nitro 中的嵌套组合函数可以访问异步上下文。这为在异步组合函数中使用组合函数提供了可能性，并减少出现 Nuxt 实例不可用 错误的机会。

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: true
  }
})

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

emitRouteChunkError

在加载 vite/webpack 块时发生错误时触发 app:chunkError 钩子。默认行为是在导航到新路由时，如果块加载失败，则重新加载新路由。

如果你将其设置为 'automatic-immediate'，Nuxt 将立即重新加载当前路由，而不是等待导航。这对于非导航触发的块错误（例如，当你的 Nuxt 应用无法加载延迟组件）很有用。此行为的潜在缺点是可能导致意外的重新加载，例如，当你的应用不需要导致错误的块时。

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

nuxt.config.ts

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

restoreState

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

为避免 hydration 错误，此功能仅在 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 > Guide > Concepts > Rendering#hybrid Rendering.

renderJsonPayloads

允许渲染支持复杂类型恢复的 JSON 有效负载。

默认启用。

nuxt.config.ts

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

noVueServer

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

nuxt.config.ts

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

payloadExtraction

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

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    payloadExtraction: 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
  }
})

阅读并编辑实时示例中的内容 https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue.

了解更多关于 View Transition API 的信息。

writeEarlyHints

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

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 > Guide > Directory Structure > Components#server Components.

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

localLayerAliases

相对于层源和根目录解析层内的 ~、~~、@ 和 @@ 别名。

默认启用。

nuxt.config.ts

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

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 安装为开发依赖项，此功能才能正常工作。

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

Nuxt 自动在预渲染的页面之间共享有效负载数据。这在使用 useAsyncData 或 useFetch 且在不同页面获取相同数据的预渲染站点时，可以显著提高性能。

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

nuxt.config.ts

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

启用此功能时，特别重要的是确保数据的任何唯一键始终解析为相同的数据。例如，如果你在动态页面中使用 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 导入。

要在浏览器中使全局变量如 Buffer 工作，你需要手动注入它们。

import { Buffer } from 'node:buffer'

globalThis.Buffer = globalThis.Buffer || Buffer

scanPageMeta

Nuxt 在构建时将 definePageMeta 中定义的一些路由元数据暴露给模块（具体包括 alias、name、path、redirect、props 和 middleware）。

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

默认情况下，页面元数据仅在所有路由通过 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: true
  }
})

了解更多关于 CookieStore 的信息。

buildCache

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

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 个缓存 tarball。

extraPageMetaExtractionKeys

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

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

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

export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ foo 可用
    },
  },
})

这允许模块在构建上下文中访问页面元数据的额外元数据。如果你在模块中使用此功能，建议同时使用你的键增强 NuxtPage 类型。

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）时，我们可以选择性地渲染一个加载屏幕（来自 ~/spa-loading-template.html）。

可以将其设置为 within，这样将渲染如下：

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

或者，你可以通过将其设置为 body 来在 Nuxt 应用根节点旁渲染模板：

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

这可以避免在 hydration 仅客户端页面时的白色闪烁。

browserDevtoolsTiming

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

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

nuxt.config.ts

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

查看 PR #29922 的实现细节。

了解更多关于 Chrome DevTools 性能 API 的信息。

debugModuleMutation

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

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

要显式启用：

nuxt.config.ts

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

查看 PR #30555 的实现细节。

lazyHydration

为 <Lazy> 组件启用 hydration 策略，通过推迟组件的 hydration 直到需要时来提高性能。

延迟 hydration 默认启用，但你可以禁用此功能：

nuxt.config.ts

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

了解更多关于延迟 hydration 的信息。

templateImportResolution

控制 Nuxt 模板中的导入解析方式。默认情况下，Nuxt 尝试相对于添加模板的模块解析模板中的导入。

此功能默认启用，如果你在某些环境中遇到解析冲突，可以禁用此行为：

nuxt.config.ts

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

查看 PR #31175 的实现细节。

decorators

此选项通过 esbuild 在整个 Nuxt/Nitro 应用中启用装饰器语法。

长期以来，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 实现。

请注意，在最终纳入 JS 标准之前，此功能可能会有变化。

使用方法

nuxt.config.ts

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

app.vue

function something (_method: () => unknown) {
  return () => '装饰后的'
}

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

const value = new SomeClass().someMethod()
// 这将返回 '装饰后的'

purgeCachedData

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

nuxt.config.ts

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

查看 PR #31379 的实现细节。

granularCachedData

在通过 watch、refreshNuxtData() 或手动 refresh() 调用刷新数据时，是否调用并使用 getCachedData 的结果来处理 useAsyncData 和 useFetch。

nuxt.config.ts

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

查看 PR #31373 的实现细节。

pendingWhenIdle

如果设置为 false，useAsyncData、useFetch、useLazyAsyncData 和 useLazyFetch 返回的 pending 对象将是一个仅在 status 也为 pending 时为 true 的计算属性。

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

nuxt.config.ts

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

Was this helpful?

Report an issue or Edit this page on GitHub

事件系统

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

功能

启用或禁用 Nuxt 的可选功能以解锁新的可能性。