实验性功能
Nuxt 实验性功能可以在 Nuxt 配置文件中启用。
在内部，Nuxt 使用 @nuxt/schema 来定义这些实验性功能。您可以参考 API 文档 或 源代码 以获取更多信息。
asyncContext
启用原生异步上下文，以便在 Nuxt 和 Nitro 中嵌套的 composable 中可以访问。这开启了在异步 composable 内部使用 composable 的可能性，并减少了出现 Nuxt instance is unavailable 错误的机会。
export default defineNuxtConfig({
experimental: {
asyncContext: true
}
})
asyncEntry
启用为 Vue bundle 生成异步入口点，以帮助模块联邦支持。
export default defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
externalVue
在构建时外部化 vue、@vue/* 和 vue-router。
默认启用。
export default defineNuxtConfig({
experimental: {
externalVue: true
}
})
treeshakeClientOnly
从服务器 bundle 中 tree shake 仅客户端组件的内容。
默认启用。
export default defineNuxtConfig({
experimental: {
treeshakeClientOnly: true
}
})
emitRouteChunkError
当加载 vite/webpack chunk 出现错误时，发出 app:chunkError 钩子。默认行为是在导航到新路由时，如果 chunk 加载失败，则执行新路由的重新加载。
如果您将其设置为 'automatic-immediate'，Nuxt 将立即重新加载当前路由，而不是等待导航。这对于非导航触发的 chunk 错误很有用，例如，当您的 Nuxt 应用程序无法加载 lazy component 时。此行为的潜在缺点是不必要的重新加载，例如，当您的应用程序不需要导致错误的 chunk 时。
您可以通过将其设置为 false 来禁用自动处理，或者通过将其设置为 manual 来手动处理 chunk 错误。
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // or 'automatic-immediate', 'manual' or false
}
})
restoreState
允许在 chunk 错误或手动调用 reloadNuxtApp() 后重新加载页面时，从 sessionStorage 恢复 Nuxt 应用程序状态。
为了避免 hydration 错误，它将仅在 Vue 应用程序挂载后应用，这意味着初始加载时可能会出现闪烁。
useState 提供显式键，因为自动生成的键可能在不同构建之间不匹配。export default defineNuxtConfig({
experimental: {
restoreState: true
}
})
inlineRouteRules
使用 defineRouteRules 在页面级别定义路由规则。
export default defineNuxtConfig({
experimental: {
inlineRouteRules: true
}
})
将根据页面的 path 创建匹配的路由规则。
renderJsonPayloads
允许渲染 JSON 有效负载，并支持复活复杂类型。
默认启用。
export default defineNuxtConfig({
experimental: {
renderJsonPayloads: true
}
})
noVueServer
禁用 Nitro 中的 Vue 服务器渲染器端点。
export default defineNuxtConfig({
experimental: {
noVueServer: true
}
})
payloadExtraction
启用提取使用 nuxt generate 生成的页面的有效负载。
export default defineNuxtConfig({
experimental: {
payloadExtraction: 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
}
})
writeEarlyHints
在使用 node 服务器时启用写入早期提示。
export default defineNuxtConfig({
experimental: {
writeEarlyHints: true
}
})
componentIslands
启用实验性组件岛支持，使用 <NuxtIsland> 和 .island.vue 文件。
export default defineNuxtConfig({
experimental: {
componentIslands: true // false or 'local+remote'
}
})
configSchema
启用配置 schema 支持。
默认启用。
export default defineNuxtConfig({
experimental: {
configSchema: true
}
})
polyfillVueUseHead
为模块、插件或依赖旧 @vueuse/head API 的用户代码添加兼容层。
export default defineNuxtConfig({
experimental: {
polyfillVueUseHead: false
}
})
respectNoSSRHeader
允许通过设置 x-nuxt-no-ssr 标头来禁用 Nuxt SSR 响应。
export default defineNuxtConfig({
experimental: {
respectNoSSRHeader: false
}
})
localLayerAliases
解析位于 layers 中的 ~、~~、@ 和 @@ 别名，使其与它们的 layer 源和根目录相关。
默认启用。
export default defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
typedPages
使用 unplugin-vue-router 启用新的实验性类型化路由器。
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 以监视源目录中的所有文件。
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular' // 'chokidar' or 'parcel' are also options
}
})
sharedPrerenderData
启用此功能会自动在预渲染的页面之间共享有效负载数据。当预渲染使用 useAsyncData 或 useFetch 并在不同页面中获取相同数据的站点时，这可以显着提高性能。
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: true
}
})
启用此功能时，特别重要的是确保数据的任何唯一键始终可解析为相同的数据。例如，如果您使用 useAsyncData 获取与特定页面相关的数据，则应提供唯一匹配该数据的键。（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 () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
// Instead, you should use a key that uniquely identifies the data fetched.
const { data } = await useAsyncData(route.params.slug, async () => {
return await $fetch(`/api/my-page/${route.params.slug}`)
})
clientNodeCompat
使用此功能，Nuxt 将在客户端构建中使用 unenv 自动 polyfill Node.js 导入。
Buffer 这样的全局变量在浏览器中工作，您需要手动注入它们。import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
此选项允许在构建时将 definePageMeta 中定义的一些路由元数据暴露给模块（特别是 alias、name、path、redirect）。
这仅适用于静态或字符串/数组，而不是变量或条件赋值。有关更多信息和上下文，请参阅 原始 issue。
也可以仅在所有路由都在 pages:extend 中注册后扫描页面元数据。然后将调用另一个钩子 pages:resolved。要启用此行为，请设置 scanPageMeta: 'after-resolve'。
如果此功能在您的项目中引起问题，您可以禁用它。
export default defineNuxtConfig({
experimental: {
scanPageMeta: false
}
})
cookieStore
启用 CookieStore 支持以监听 cookie 更新（如果浏览器支持）并刷新 useCookie ref 值。
export default defineNuxtConfig({
experimental: {
cookieStore: true
}
})
buildCache
基于配置和源文件的哈希值缓存 Nuxt 构建工件。
export default defineNuxtConfig({
experimental: {
buildCache: true
}
})
启用后，对以下文件的更改将触发完全重建
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lockb
此外，对 srcDir 中文件的任何更改都将触发 Vue 客户端/服务器 bundle 的重建。Nitro 将始终被重建（尽管正在进行工作以允许 Nitro 公布其可缓存的工件及其哈希值）。
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 类型。
normalizeComponentNames
确保自动生成的 Vue 组件名称与您用于自动导入组件的完整组件名称相匹配。
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: true
}
})
默认情况下，如果您没有手动设置，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 -->
这避免了在水合仅客户端页面时出现白屏闪烁。
decorators
此选项允许在您的整个 Nuxt/Nitro 应用中启用装饰器语法，由 esbuild 提供支持。
长期以来，TypeScript 通过 compilerOptions.experimentalDecorators 支持装饰器。 此实现早于 TC39 标准化过程。 现在，装饰器是一个 第三阶段提案，并且在 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 实现的支持。
用法
export default defineNuxtConfig({
experimental: {
decorators: true,
},
})
function something (_method: () => unknown) {
return () => 'decorated'
}
class SomeClass {
@something
public someMethod () {
return 'initial'
}
}
const value = new SomeClass().someMethod()
// this will return 'decorated'