实验性特性
在 Nuxt 配置文件中可以启用 Nuxt 实验性特性。
内部地，Nuxt 使用 @nuxt/schema 来定义这些实验性特性。您可以参考 API 文档 或 源代码 了解更多信息。
asyncContext
启用原生异步上下文，以便在 Nuxt 和 Nitro 中为嵌套组合使用。这打开了使用组合在异步组合内使用和减少获得 Nuxt 实例不可用 错误的机会的可能性。
export default defineNuxtConfig({
experimental: {
asyncContext: true
}
})
asyncEntry
启用 Vue 包的异步入口点生成，以支持模块联营。
export default defineNuxtConfig({
experimental: {
asyncEntry: true
}
})
externalVue
在构建时外部化 vue、@vue/* 和 vue-router。
默认启用。
export default defineNuxtConfig({
experimental: {
externalVue: true
}
})
emitRouteChunkError
当加载 vite/webpack 块时出现错误时，会发出 app:chunkError 钩子。默认行为是在导航到新路由时重新加载新路由，当块加载失败时。
如果将其设置为 'automatic-immediate'，Nuxt 将立即重新加载当前路由，而不是等待导航。这对于不是由导航触发的块错误非常有用，例如，当您的 Nuxt 应用无法加载 懒加载组件 时。这种行为的一个潜在缺点是可能会出现不必要的重新加载，例如，当您的应用不需要导致错误的块时。
您可以通过将其设置为 false 来禁用自动处理，或将它设置为 manual 来手动处理块错误。
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // 或 'automatic-immediate', 'manual' 或 false
}
})
restoreState
允许在重新加载页面（在块错误后或手动调用 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 或 'local+remote'
}
})
localLayerAliases
根据其层源和根目录的位置，在层内解析 ~、~~、@ 和 @@ 别名。
默认启用。
export default defineNuxtConfig({
experimental: {
localLayerAliases: true
}
})
typedPages
启用新的实验性类型安全路由器使用 unplugin-vue-router。
export default defineNuxtConfig({
experimental: {
typedPages: true
}
})
开箱即用地，这会使 useAsyncData 或 useFetch 的类型安全使用navigateTo、<NuxtLink>、router.push() 以及更多。
您甚至可以在页面中获取类型化的参数，通过使用 const route = useRoute('route-name')。
watcher
设置一个替代的 watcher，它将在 Nuxt 中用作监听服务。
Nuxt 默认使用 chokidar-granular，它将忽略顶级目录（如 node_modules 和 .git），这些目录被排除在监控之外。
您可以将这个设置为 parcel 来使用 @parcel/watcher，这可能在大项目或在 Windows 平台上提高性能。
您也可以设置为 chokidar 来监控源目录中的所有文件。
export default defineNuxtConfig({
experimental: {
watcher: 'chokidar-granular' // 'chokidar' 或 'parcel' 也是选项
}
})
sharedPrerenderData
启用此功能后，自动在预渲染的页面之间共享使用 useAsyncData 或 useFetch 生成的页面有效负载数据。
export default defineNuxtConfig({
experimental: {
sharedPrerenderData: true
}
})
在启用此功能时，确保任何数据唯一键都可以解析为相同的数据特别重要。例如，如果您使用 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 导入的 polyfill。
Buffer 这样的全局变量在浏览器中工作，您需要手动注入它们。import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
此选项允许在构建时将一些由 definePageMeta 定义的路由元数据暴露给模块（特别是 alias、name、path、redirect）。
这个功能仅在静态或字符串/数组而不是变量或条件赋值时工作。更多信息请查看 原始问题。
在所有路由在 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
Caches Nuxt build artifacts based on a hash of the configuration and source files.
export default defineNuxtConfig({
experimental: {
buildCache: true
}
})
When enabled, changes to the following files will trigger a full rebuild:
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lockb
In addition, any changes to files within srcDir will trigger a rebuild of the Vue client/server bundle. Nitro will always be rebuilt (though work is in progress to allow Nitro to announce its cacheable artifacts and their hashes).
normalizeComponentNames
Ensure that auto-generated Vue component names match the full component name you would use to auto-import the component.
export default defineNuxtConfig({
experimental: {
normalizeComponentNames: true
}
})
By default, if you haven't set it manually, Vue will assign a component name that matches the filename of the component.
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
In this case, the component name would be MyComponent, as far as Vue is concerned. If you wanted to use <KeepAlive> with it, or identify it in the Vue DevTools, you would need to use this component.
But in order to auto-import it, you would need to use SomeFolderMyComponent.
By setting experimental.normalizeComponentNames, these two values match, and Vue will generate a component name that matches the Nuxt pattern for component naming.