实验性功能
启用 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
启用可在 Nuxt 和 Nitro 中的嵌套组合式函数中访问的本机异步上下文。这开辟了在异步组合式函数中使用组合式函数并减少获得 Nuxt 实例不可用 错误的可能性。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
asyncContext: true,
},
})
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 钩子。默认行为是在导航到新路由时执行新路由的重新加载，当块加载失败时。
默认情况下，当导航到新路由时块加载失败时，Nuxt 也会执行新路由的重新加载（automatic）。
设置 automatic-immediate 将导致 Nuxt 在块加载失败时立即执行当前路由的重新加载（而不是等待导航）。这对于非导航触发的块错误很有用，例如，当您的 Nuxt 应用程序未能加载惰性组件时。此行为的潜在缺点是意外重新加载，例如，当您的应用程序不需要导致错误的块时。
您可以通过将其设置为 false 来禁用自动处理，或通过将其设置为 manual 来手动处理块错误。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic', // 或 'automatic-immediate'、'manual' 或 false
},
})
enforceModuleCompatibility
如果 Nuxt 模块不兼容，Nuxt 是否应该抛出错误（并且加载失败）。
此功能默认禁用。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
enforceModuleCompatibility: true,
},
})
restoreState
允许在块错误或手动 reloadNuxtApp()`` 调用后重新加载页面时从 sessionStorage` 恢复 Nuxt 应用程序状态。
为避免水合错误，它仅在 Vue 应用程序已挂载后才应用，这意味着初始加载时可能会闪烁。
在启用此功能之前请仔细考虑，因为它可能导致意外行为，
并考虑为 `useState`` 提供显式键，因为自动生成的键可能在不同构建之间不匹配。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
restoreState: true,
},
})
inlineRouteRules
使用 `defineRouteRules`` 在页面级别定义路由规则。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true,
},
})
匹配路由规则将基于页面的 path 创建。
在 defineRouteRules 实用程序中阅读更多信息。
::
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,
},
})
viewTransition
启用客户端路由器的 View Transition API 集成。
nuxt.config.ts
export default defineNuxtConfig({
experimental: {
viewTransition: true,
},
})
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'
},
})
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') 在页面中获取类型化参数。如果您使用不带
shamefully-hoist=true 的 pnpm，您需要将 unplugin-vue-router 作为提升模式添加到您的 pnpm-workspace.yaml 中，以便此功能工作。publicHoistPattern:
- "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 (_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 导入。要使像
Buffer 这样的全局变量在浏览器中工作，您需要手动注入它们。import { Buffer } from 'node:buffer'
globalThis.Buffer ||= Buffer
scanPageMeta
Nuxt 在构建时向模块（特别是alias、name、path、redirect、props 和 middleware）暴露在 definePageMeta 中定义的一些路由元数据。这仅适用于静态或字符串/数组，而不适用于变量或条件赋值。请参阅原始 issue 以获取更多信息和上下文。默认情况下，页面元数据仅在所有路由已在 pages:extend 中注册后才扫描。然后将调用另一个钩子 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,
},
})
buildCache
基于配置和源文件的哈希缓存 Nuxt 构建产物。这仅适用于应用程序的 Vue/Nitro 部分在srcDir 和 serverDir 内的源文件。此标志默认禁用，但您可以启用它：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,
},
})
目录结构
├─ components/
├─── SomeFolder/
├───── MyComponent.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 加载模板 -->
browserDevtoolsTiming
为浏览器 devtools 中的 Nuxt 钩子启用性能标记。这添加了您可以在基于 Chromium 的浏览器的 Performance 选项卡中跟踪的性能标记，这对于调试和优化性能很有用。这在开发模式下默认启用。如果您需要禁用此功能，可以这样做：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
browserDevtoolsTiming: false,
},
})
debugModuleMutation
记录模块上下文中对nuxt.options 的更改，有助于调试 Nuxt 初始化期间模块所做的配置更改。这默认在启用 debug 模式时启用。如果您需要禁用此功能，可以这样做：要显式启用它：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
debugModuleMutation: true,
},
})
lazyHydration
这为<Lazy> 组件启用水合策略，通过延迟组件水合直到需要它们来提高性能。惰性水合默认启用，但您可以禁用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
lazyHydration: false,
},
})
templateImportResolution
禁用从添加模板的模块的路径解析到 Nuxt 模板中的导入。默认情况下，Nuxt 尝试相对于添加它们的模块解析模板中的导入。将其设置为false 会禁用此行为，如果您在某些环境中遇到解析冲突，这可能很有用。此标志默认启用，但您可以禁用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
templateImportResolution: false,
},
})
templateRouteInjection
默认情况下，由自动导入的useRoute() 组合式函数返回的路由对象与 <NuxtPage> 中查看的当前页面保持同步。这对于 vue-router 导出的 useRoute 或 Vue 模板中可用的默认 $route 对象并非如此。通过启用此选项，将注入一个 mixin 以保持 $route 模板对象与 Nuxt 管理的 useRoute() 同步。此标志默认启用，但您可以禁用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
templateRouteInjection: false,
},
})
decorators
此选项启用通过 esbuild 在整个 Nuxt/Nitro 应用程序中启用装饰器语法。长期以来，TypeScript 通过compilerOptions.experimentalDecorators 支持装饰器。此实现早于 TC39 标准化过程。现在，装饰器是 第 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/app.vue
function something (_method: () => unknown) {
return () => '已装饰'
}
class SomeClass {
@something
public someMethod () {
return '初始'
}
}
const value = new SomeClass().someMethod()
// 这将返回 '已装饰'
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 静态和 asyncData 缓存。Nuxt 将自动从useAsyncData 和 nuxtApp.static.data 清除缓存的数据。这有助于防止内存泄漏，并确保在需要时加载新数据，但可以禁用它。此标志默认启用，但您可以禁用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
purgeCachedData: false,
},
})
granularCachedData
是否在为useAsyncData 和 useFetch 刷新数据时（无论是通过 watch、refreshNuxtData() 还是手动 refresh() 调用）调用并使用来自 getCachedData 的结果。此标志默认启用，但您可以禁用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
granularCachedData: false,
},
})
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 通过使用导入映射来解析包的入口块来改进块稳定性。这将在您的<head> 标记的顶部注入导入映射：<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
#entry。这意味着对入口的更改不会使其他未更改的块失效。如果您已配置
如果您需要禁用此功能，可以这样做：vite.build.target 以包含不支持导入映射的浏览器，或者如果您已配置 vite.build.rollupOptions.output.entryFileNames 为不包含 [hash] 的值，Nuxt 将智能地禁用此功能。nuxt.config.ts
export default defineNuxtConfig({
experimental: {
entryImportMap: false,
},
// 或者，更好的是，只需告诉 vite 您期望的目标
// nuxt 将会尊重它
vite: {
build: {
target: 'safari13',
},
},
})
typescriptPlugin
通过@dxup/nuxt 模块启用增强的 TypeScript 开发者体验。此实验性插件提供了改进的 TypeScript 集成和开发工具，以便在 Nuxt 应用程序中使用 TypeScript 时提供更好的 DX。此标志默认禁用，但您可以启用此功能：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
typescriptPlugin: true,
},
})
要使用此功能，您需要：
- 将
typescript安装为依赖项 - 配置 VS Code 使用您的工作区 TypeScript 版本（请参阅 VS Code 文档
viteEnvironmentApi
启用 Vite 6 的新的 Environment API 以改进构建配置和插件架构。当您将future.compatibilityVersion 设置为 5 时，默认启用此功能。您也可以显式启用它以进行测试：nuxt.config.ts
export default defineNuxtConfig({
experimental: {
viteEnvironmentApi: true,
},
})