实验性功能

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

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

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

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

alwaysRunFetchOnKeyChange

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

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

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

nuxt.config.ts

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

appManifest

使用应用程序清单 (app manifests) 来尊重客户端的路由规则。

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

nuxt.config.ts

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

asyncContext

启用原生的异步上下文 (async context)，以便在 Nuxt 和 Nitro 中可以访问嵌套的 composables。这为在异步 composables 内部使用 composables 提供了可能性，并减少了出现 Nuxt 实例不可用 错误的可能性。

nuxt.config.ts

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

在 GitHub pull-request 上查看完整解释。

asyncEntry

启用 Vue bundle 的异步入口点生成，以支持模块联邦 (module federation)。

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

此功能会将内联处理函数转换为动态导入的块

<!-- Before -->
<script setup>
const { data } = await useAsyncData('user', async () => {
  return await $fetch('/api/user')
})
</script>

<!-- After transformation -->
<script setup>
const { data } = await useAsyncData('user', () =>
  import('/generated-chunk.js').then(r => r.default()),
)
</script>

这种转换的好处是我们可以分离数据获取逻辑——同时仍然允许在需要时加载代码。

此功能仅推荐用于启用了有效负载提取的静态构建，并且数据不需要在运行时重新获取。

emitRouteChunkError

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

默认情况下，当块加载失败时，Nuxt 也会在导航到新路由时重新加载新路由（automatic）。

将 automatic-immediate 设置为 automatic-immediate 将导致 Nuxt 在块加载失败时立即重新加载当前路由（而不是等待导航）。这对于非导航触发的块错误非常有用，例如当您的 Nuxt 应用无法加载延迟组件时。这种行为的一个潜在缺点是出现不必要的重新加载，例如当您的应用不需要导致错误的块时。

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

nuxt.config.ts

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

enforceModuleCompatibility

如果 Nuxt 模块不兼容，Nuxt 是否应该抛出错误（并停止加载）。

此功能默认禁用。

nuxt.config.ts

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

restoreState

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

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

在启用此功能之前请仔细考虑，因为它可能导致意外行为，并考虑为 useState 提供明确的 key，因为自动生成的 key 在不同构建之间可能不匹配。

nuxt.config.ts

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

inlineRouteRules

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

nuxt.config.ts

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

将根据页面的 path 创建匹配的路由规则。

在 defineRouteRules 工具中阅读更多信息。

在 文档 > 4.x > 指南 > 概念 > 渲染#混合渲染 中阅读更多内容。

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: {
    // Payload files will be generated for these cached routes
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: true },
  },
})

clientFallback

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

nuxt.config.ts

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

crossOriginPrefetch

使用推测规则 API (Speculation Rules API) 启用跨源预取。

nuxt.config.ts

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

阅读有关推测规则 API的更多信息。

viewTransition

启用视图转换 API (View Transition API) 与客户端路由器的集成。

nuxt.config.ts

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

在 https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue 中阅读和编辑实时示例。

阅读有关视图转换 API的更多信息。

writeEarlyHints

在使用 node 服务器时启用写入早期提示 (early hints)。

nuxt.config.ts

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

componentIslands

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

nuxt.config.ts

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

在 文档 > 4.x > 目录结构 > 应用 > 组件#服务器组件 中阅读更多内容。

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

localLayerAliases

解析位于层 (layers) 中的 ~、~~、@ 和 @@ 别名，相对于它们的层源和根目录。

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

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

如果您在没有 shamefully-hoist=true 的情况下使用 pnpm，则需要将 unplugin-vue-router 安装为 devDependency 才能使此功能正常工作。

watcher

设置一个替代的 watcher，它将用作 Nuxt 的监视服务。

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

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

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

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular', // 'chokidar' or 'parcel' are also options
  },
})

sharedPrerenderData

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

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

nuxt.config.ts

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

启用此功能时，务必确保任何唯一数据的 key 始终可以解析为相同的数据。例如，如果您使用 useAsyncData 来获取与特定页面相关的数据，您应该提供一个唯一匹配该数据的 key。（useFetch 应该自动为您完成此操作。）

// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// Instead, you should use a key that uniquely identifies the data fetched.
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

Nuxt 在构建时将从 definePageMeta 定义的路由元数据暴露给模块（特别是 alias、name、path、redirect、props 和 middleware）。

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

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

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

nuxt.config.ts

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

cookieStore

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

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

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 客户端/服务器 bundle 的重建。Nitro 将始终重建（尽管正在努力使 Nitro 能够宣布其可缓存的工件及其哈希值）。

最多保留 10 个缓存 tarball。

checkOutdatedBuildInterval

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

设置为 false 以禁用。

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 hour, or false to disable
  },
})

extraPageMetaExtractionKeys

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

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

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

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

这允许模块在构建上下文中访问页面元数据的其他元数据。如果您在模块中使用此功能，建议也使用您的键来增强 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）时，我们会选择性地渲染一个加载屏幕（来自 ~/spa-loading-template.html）。

它可以设置为 within，它将这样渲染

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

或者，您可以将其设置为 body，将模板与 Nuxt 应用根目录一起渲染

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

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

browserDevtoolsTiming

为 Nuxt hook 在浏览器开发者工具中启用性能标记 (performance markers)。这会添加您可以在基于 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> 组件启用了水合策略，通过推迟组件的水合直到需要它们，从而提高了性能。

延迟水合默认启用，但您可以禁用此功能

nuxt.config.ts

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

阅读有关延迟水合的更多信息。

templateImportResolution

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

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

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

nuxt.config.ts

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

有关实现细节，请参阅 PR #31175。

templateRouteInjection

默认情况下，自动导入的 useRoute() composable 返回的 route 对象与 <NuxtPage> 中当前显示的页面保持同步。这对于 vue-router 导出的 useRoute 或在 Vue 模板中可用的默认 $route 对象不成立。

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

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

nuxt.config.ts

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

decorators

此选项支持在整个 Nuxt/Nitro 应用中启用装饰器语法，由esbuild.

提供支持。长期以来，TypeScript 一直通过 compilerOptions.experimentalDecorators 支持装饰器。此实现早于 TC39 标准化过程。现在，装饰器是Stage 3 Proposal，并在 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/app.vue

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

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

const value = new SomeClass().someMethod()
// this will return 'decorated'

defaults

这允许指定核心 Nuxt 组件和 composables 的默认选项。

这些选项将来可能会移至其他地方，例如移至 app.config 或 app/ 目录。

nuxt.config.ts

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

purgeCachedData

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

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

使用 head 优化

添加 capo.js head 插件，以便以更高效的方式在 head 中渲染标签。
使用哈希水合插件来减少初始水合

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

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) 来解析 bundle 的入口块，从而提高块的稳定性。

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

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

在 Vite 发出的脚本块中，导入将来自 #entry。这意味着入口的更改不会使其他保持不变的块失效。

如果您的 vite.build.target 配置包含不支持导入映射的浏览器，或者您的 vite.build.rollupOptions.output.entryFileNames 配置为不包含 [hash] 的值，Nuxt 会智能地禁用此功能。

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

nuxt.config.ts

export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // or, better, simply tell vite your desired target
  // which nuxt will respect
  vite: {
    build: {
      target: 'safari13',
    },
  },
})

typescriptPlugin

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

此实验性插件为使用 Nuxt 应用程序中的 TypeScript 提供了改进的 TypeScript 集成和开发工具，以获得更好的 DX。

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

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 功能以解锁新的可能性。