---
title: "实验性功能"
description: "启用 Nuxt 实验性功能，解锁更多可能。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/experimental-features"
---
# 实验性功能

> 启用 Nuxt 实验性功能，解锁更多可能。

可以在 Nuxt 配置文件中启用 Nuxt 实验性功能。

Nuxt 内部使用 `@nuxt/schema` 定义这些实验性功能。更多信息请参阅 [API 文档](https://nuxt.zhcndoc.com/docs/3.x/guide/going-further/experimental-features)或[源代码](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts)。

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

## alwaysRunFetchOnKeyChange

是否在 key 变化时运行 `useFetch`，即使设置了 `immediate: false` 且尚未触发。

当 `immediate: true` 或已触发时，`useFetch` 与 `useAsyncData` 总会在 key 变化时运行。

该标志默认禁用，但你可以启用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})
```

## appManifest

使用应用清单以便在客户端遵守路由规则。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    appManifest: false,
  },
})
```

## asyncContext

启用原生 async 上下文，使其在 Nuxt 和 Nitro 中的嵌套组合式函数中可访问。这使得可以在异步组合式函数内部使用其他组合式函数，并减少出现 `Nuxt instance is unavailable` 错误的概率。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    asyncContext: true,
  },
})
```

::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/pull/20918" target="_blank"}
在 GitHub 拉取请求中查看完整说明。
::

## asyncEntry

启用为 Vue 包生成异步入口点，有助于模块联邦支持。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    asyncEntry: true,
  },
})
```

## externalVue

构建时将 `vue`、`@vue/*` 和 `vue-router` 外部化。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    externalVue: false,
  },
})
```

::warning
该功能可能在不久的将来被移除。
::

## extractAsyncDataHandlers

将 `useAsyncData` 和 `useLazyAsyncData` 调用中的处理函数提取到单独的代码块中，以改善代码拆分和缓存效率。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true,
  },
})
```

该功能会将内联处理函数转换为动态导入的代码块：

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

```vue
<!-- 转换后 -->
<script setup>
const { data } = await useAsyncData('user', () =>
  import('/generated-chunk.js').then(r => r.default()),
)
</script>
```

此转换的优势在于，我们可以拆分数据获取逻辑，同时仍允许按需加载代码。

::important
此功能仅推荐用于**静态构建**且启用了负载提取、且数据在运行时无需重新获取的场景。
::

## emitRouteChunkError

当加载 vite/webpack 分块失败时，触发 `app:chunkError` 钩子。默认行为是在导航到新路由时，若分块加载失败则刷新新路由。

若设置为 `'automatic-immediate'`，则 Nuxt 会立即刷新当前路由，而不是等待导航。这对于非导航触发的分块错误（例如，Nuxt 应用加载懒组件失败）非常有用。但此行为可能导致不必要的刷新，例如应用不需要导致错误分块时。

设置 `automatic-immediate` 会使 Nuxt 在分块加载失败时立即刷新当前路由（而不是等待导航）。这对于非导航触发的分块错误非常有用，例如 Nuxt 应用加载[懒加载组件](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/components#dynamic-imports)失败时。这种行为的潜在缺点是可能导致不必要的刷新，例如应用并不需要导致错误的分块时。

将其设置为 `false` 可禁用自动处理，也可以将其设置为 `manual`，手动处理分块错误。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic', // 或 'automatic-immediate', 'manual' 或 false
  },
})
```

## enforceModuleCompatibility

是否在 Nuxt 模块不兼容时抛出错误（并阻止加载）。

该功能默认禁用。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    enforceModuleCompatibility: true,
  },
})
```

## restoreState

允许在分块错误或手动调用 [`reloadNuxtApp()`](https://nuxt.zhcndoc.com/docs/3.x/api/utils/reload-nuxt-app) 后重新加载页面时，从 `sessionStorage` 恢复 Nuxt 应用状态。

为避免水合错误，此功能仅在 Vue 应用挂载后应用，这意味着初次加载时可能出现闪烁。

::important
启用此功能前请仔细考虑，因为它可能导致意外行为；同时考虑为 [`useState`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-state) 提供显式键，因为自动生成的键在不同构建之间可能不匹配。
::

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    restoreState: true,
  },
})
```

## inlineRouteRules

使用 [`defineRouteRules`](https://nuxt.zhcndoc.com/docs/3.x/api/utils/define-route-rules) 在页面级别定义路由规则。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true,
  },
})
```

将基于页面的 `path` 创建匹配的路由规则。

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/api/utils/define-route-rules" icon="i-lucide-square-function"}
阅读更多 `defineRouteRules` 工具的相关信息。
::

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal"}
::

## renderJsonPayloads

允许渲染包含复杂类型复活支持的 JSON 负载。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: false,
  },
})
```

## noVueServer

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

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    noVueServer: true,
  },
})
```

## parseErrorData

是否在渲染服务器错误页面时解析 `error.data`。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    parseErrorData: false,
  },
})
```

## payloadExtraction

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

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
})
```

负载提取同样适用于使用 ISR（增量静态再生）或 SWR（陈旧-重新验证）缓存策略的路由。这样CDN 可与 HTML 一起缓存负载文件，提升缓存路由的客户端导航性能。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
  routeRules: {
    // 将为这些缓存路由生成负载文件
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: true },
  },
})
```

## clientFallback

启用实验性的 [`<NuxtClientFallback>`](https://nuxt.zhcndoc.com/docs/3.x/api/components/nuxt-client-fallback) 组件，以便在 SSR 出错时在客户端渲染内容。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    clientFallback: true,
  },
})
```

## crossOriginPrefetch

启用使用 Speculation Rules API 的跨源预取。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})
```

::read-more{icon="i-simple-icons-w3c" to="https://wicg.github.io/nav-speculation/prefetch.html" target="_blank"}
阅读更多关于 **Speculation Rules API**。
::

## viewTransition

启用 View Transition API 与客户端路由器集成。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})
```

::link-example{to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue" target="_blank"}
::

::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" target="_blank"}
阅读更多关于 **View Transition API**。
::

## writeEarlyHints

使用 Node 服务器时启用写入早期提示。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    writeEarlyHints: true,
  },
})
```

## componentIslands

启用实验性的组件岛支持，包括 [`<NuxtIsland>`](https://nuxt.zhcndoc.com/docs/3.x/api/components/nuxt-island) 和 `.island.vue` 文件。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    componentIslands: true, // 也可设置为 false 或 'local+remote'
  },
})
```

::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/components#server-components"}
::

::read-more{icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt/issues/19772" target="_blank"}
你可以在 GitHub 上关注服务器组件的路线图。
::

## localLayerAliases

解析位于层内的 `~`、`~~`、`@` 和 `@@` 别名，基于其层源和根目录。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    localLayerAliases: false,
  },
})
```

## typedPages

启用新的实验性类型化路由，使用 [`unplugin-vue-router`](https://github.com/posva/unplugin-vue-router)。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    typedPages: true,
  },
})
```

默认情况下，这将启用对 [`navigateTo`](https://nuxt.zhcndoc.com/docs/3.x/api/utils/navigate-to)、[`<NuxtLink>`](https://nuxt.zhcndoc.com/docs/3.x/api/components/nuxt-link)、[`router.push()`](https://nuxt.zhcndoc.com/docs/3.x/api/composables/use-router) 等的类型化使用。

甚至可以在页面内通过 `const route = useRoute('route-name')` 获取类型化的参数。

::important
如果你使用 `pnpm` 且未设置 `shamefully-hoist=true`，你需要在 `pnpm-workspace.yaml` 中将 `unplugin-vue-router` 添加为 hoist 模式，以使该功能正常工作。

```yaml
publicHoistPattern:
  - "unplugin-vue-router"
```
::

::video-accordion{title="观看 Daniel Roe 讲解 Nuxt 类型安全路由的视频" videoId="SXk-L19gTZk"}
::

## watcher

设置 Nuxt 监视服务的替代监视器。

Nuxt 默认使用 `chokidar-granular`，该模块会忽略顶层目录（如 `node_modules` 和 `.git`）的监视。

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

也可以设置为 `chokidar` 监视源目录下的所有文件。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular', // 可选 'chokidar' 或 'parcel'
  },
})
```

## sharedPrerenderData

启用此功能后，自动在预渲染页面间共享负载*数据*。这在使用 `useAsyncData` 或 `useFetch` 并在多个页面中获取相同数据的站点预渲染时，能显著提升性能。

你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    sharedPrerenderData: false,
  },
})
```

::video-accordion{title="观看 Alexander Lichter 介绍实验性 sharedPrerenderData 的视频" videoId="1jUupYHVvrU"}
::

启用该功能时，确保任何数据的唯一键始终指向相同数据非常重要。例如，若使用 `useAsyncData` 获取特定页面的数据，应提供唯一匹配该数据的键。（`useFetch` 会自动处理这点。）

```ts
// 在动态页面（如 `[slug].vue`）中，若未将路由 slug 反映到键中，则不安全。
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`](https://github.com/unjs/unenv) 为 Node.js 导入进行 polyfill。

::note
若需在浏览器端使用全局变量如 `Buffer`，需手动注入：

```ts
import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer
```
::

## scanPageMeta

允许在构建时向模块暴露通过 `definePageMeta` 定义的部分路由元数据（具体包含 `alias`、`name`、`path`、`redirect`、`props` 和 `middleware`）。

仅支持静态值或字符串/数组，不支持变量或条件赋值。详情见[原始 Issue](https://github.com/nuxt/nuxt/issues/24770)。

默认情况下，页面元数据仅在所有路由通过 `pages:extend` 注册后扫描，随后会触发钩子 `pages:resolved`。

若该功能引发问题，亦可禁用。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: false,
  },
})
```

## cookieStore

启用 CookieStore 支持，监听浏览器 Cookie 更新（如果浏览器支持），并刷新 `useCookie` 的响应式值。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    cookieStore: false,
  },
})
```

::read-more{icon="i-simple-icons-mdnwebdocs" to="https://developer.mozilla.org/en-US/docs/Web/API/CookieStore" target="_blank"}
阅读更多关于 **CookieStore**。
::

## buildCache

基于配置和源码文件的哈希缓存 Nuxt 构建产物。

仅对 `srcDir` 和 `serverDir` 中用于 Vue/Nitro 应用的源码文件有效。

该标志默认禁用，但你可以启用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    buildCache: true,
  },
})
```

启用时，以下文件的变更会触发完整重建：

```bash [目录结构]
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lock
bun.lockb
```

此外，`srcDir` 目录内文件的变更会触发 Vue 客户端/服务器包的重建。Nitro 始终会重建（并且正在开发中，使 Nitro 能声明其缓存产物及哈希）。

::note
最多保留 10 个缓存压缩包。
::

## checkOutdatedBuildInterval

设置检测新构建的时间间隔（毫秒）。当 `experimental.appManifest` 为 `false` 时禁用。

设置为 `false` 可禁用此功能。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 小时，或 false 禁用
  },
})
```

## extraPageMetaExtractionKeys

`definePageMeta()` 宏用于收集页面的构建时元数据。Nuxt 本身支持部分固定键，用于驱动重定向、页面别名和自定义路径等功能。

该选项允许在使用 `scanPageMeta` 时传入额外需要提取的键。

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

```ts
export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ 可以访问 foo
    },
  },
})
```

这使模块可以在构建上下文中访问页面元数据中的其他信息。如果你在模块中使用此功能，建议同时[使用你的键扩展 `NuxtPage` 类型](https://nuxt.zhcndoc.com/docs/3.x/directory-structure/pages#typing-custom-metadata)。

## navigationRepaint

等待单个动画帧后再导航，这给浏览器重新绘制的机会，从而响应用户交互。

这可以降低在预渲染路由上导航时的 INP（交互到完成延迟）。

该标志默认启用，但你可以禁用此功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    navigationRepaint: false,
  },
})
```

## normalizeComponentNames

Nuxt 更新自动生成的 Vue 组件名，使其与用于自动导入组件时的完整组件名一致。

如果遇到问题，可以禁用该功能。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: false,
  },
})
```

默认情况下，若未手动设置，Vue 会为组件赋予与文件名匹配的组件名。

```bash [目录结构]
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
```

此例中，Vue 将组件名视为 `MyComponent`。若要与 `<KeepAlive>` 配合或在 Vue DevTools 中识别，须使用该名称。

但若要自动导入，同一组件需使用 `SomeFolderMyComponent`。

启用 `experimental.normalizeComponentNames` 后，这两个名称将保持一致，Vue 会生成与 Nuxt 命名方案匹配的组件名。

## spaLoadingTemplateLocation

渲染客户端专用页面（`ssr: false`）时，可选择渲染加载屏幕（来自 `app/spa-loading-template.html`）。

设置为 `within` 时，渲染结构为：

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

或设置为 `body`，则在 Nuxt 应用根节点旁渲染：

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

这避免了客户端专用页面水合时的白屏闪烁。

## browserDevtoolsTiming

启用浏览器开发者工具中 Nuxt 钩子的性能标记。你可以在基于 Chromium 的浏览器的性能（Performance）标签页中跟踪这些标记，对于调试和优化性能非常有用。

开发模式下默认启用。若需要禁用，配置如下：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    browserDevtoolsTiming: false,
  },
})
```

::read-more
```yaml [props]
icon: i-simple-icons-github
color: gray
to: https://github.com/nuxt/nuxt/pull/29922
target: _blank
```
查看 PR #29922 的实现细节。
::

::read-more
```yaml [props]
icon: i-simple-icons-googlechrome
color: gray
to: https://developer.chrome.com/docs/devtools/performance/extension#tracks
target: _blank
```
了解更多 Chrome DevTools Performance API。
::

## debugModuleMutation

记录模块上下文中对 `nuxt.options` 的变更，有助于调试 Nuxt 初始化期间模块对配置的修改。

当启用 `debug` 模式时此功能默认开启。若需禁用，可使用：

若需显式启用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    debugModuleMutation: true,
  },
})
```

::read-more
```yaml [props]
icon: i-simple-icons-github
color: gray
to: https://github.com/nuxt/nuxt/pull/30555
target: _blank
```
查看 PR #30555 的实现细节。
::

## lazyHydration

为 `<Lazy>` 组件启用懒加载水合策略，延迟组件水合以提升性能。

默认启用，若需禁用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    lazyHydration: false,
  },
})
```

::read-more{icon="i-simple-icons-github" color="gray" to="https://nuxt.zhcndoc.com/docs/3.x/directory-structure/components#delayed-or-lazy-hydration"}
阅读更多关于懒水合的信息。
::

## templateImportResolution

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

该标志默认启用，但在某些环境出现解析冲突时，你可以禁用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    templateImportResolution: false,
  },
})
```

::read-more
```yaml [props]
icon: i-simple-icons-github
color: gray
to: https://github.com/nuxt/nuxt/pull/31175
target: _blank
```
查看 PR #31175 的实现细节。
::

## templateRouteInjection

默认情况下，自动导入的 `useRoute()` 组合函数返回的路由对象保持与 `<NuxtPage>` 中当前页面同步。这不适用于 `vue-router` 导出的 `useRoute` 或 Vue 模板中的默认 `$route` 对象。

启用此选项会注入一个混入，以保持模板中的 `$route` 对象与 Nuxt 管理的 `useRoute()` 同步。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    templateRouteInjection: false,
  },
})
```

## decorators

启用全局装饰器语法，基于 [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3) 实现。

TypeScript 长期通过 `compilerOptions.experimentalDecorators` 支持装饰器，但该实现早于 TC39 标准流程。现今装饰器为 [Stage 3 提案](https://github.com/tc39/proposal-decorators)，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 以前的 `experimentalDecorators` 实现。

::warning
注意该语法可能在最终定稿前依然会有变动。
::

### 使用方法

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    decorators: true,
  },
})
```

```ts [app.vue]
function something (_method: () => unknown) {
  return () => 'decorated'
}

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

const value = new SomeClass().someMethod()
// 返回 'decorated'
```

## defaults

此项允许为核心 Nuxt 组件和组合函数指定默认选项。

这些选项将来可能迁移到其他位置，比如 `app.config` 或 `app/` 目录。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        componentName: 'NuxtLink',
        prefetch: true,
        prefetchOn: {
          visibility: true,
        },
      },
      useAsyncData: {
        deep: true,
      },
    },
  },
})
```

## purgeCachedData

Nuxt 会自动清理 `useAsyncData` 和 `nuxtApp.static.data` 的缓存数据，帮助防止内存泄漏，并确保必要时加载最新数据。可通过配置关闭此功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false,
  },
})
```

::read-more
```yaml [props]
icon: i-simple-icons-github
color: gray
to: https://github.com/nuxt/nuxt/pull/31379
target: _blank
```
查看 PR #31379 的实现细节。
::

## granularCachedData

控制刷新 `useAsyncData` 和 `useFetch` 数据时（通过 `watch`、`refreshNuxtData()` 或手动调用 `refresh()`）是否调用并使用 `getCachedData` 结果。

该标志默认启用，但你可以禁用该功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
  },
})
```

::read-more
```yaml [props]
icon: i-simple-icons-github
color: gray
to: https://github.com/nuxt/nuxt/pull/31373
target: _blank
```
查看 PR #31373 的实现细节。
::

## headNext

使用头标签优化：

- 添加 capo.js 头插件，以更高效地渲染头标签中的内容。
- 使用哈希水合插件减少初始水合工作。

该标志默认启用，但你可以禁用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    headNext: false,
  },
})
```

## pendingWhenIdle

对于 `useAsyncData` 和 `useFetch`，是否在数据尚未开始获取时将 `pending` 设为 `true`。

该标志默认禁用，但你可以启用此功能：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})
```

## entryImportMap

默认情况下，Nuxt 通过使用导入映射（import map）来提升代码块的稳定性，从而解析打包的入口代码块。

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

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

在 Vite 输出的脚本代码块中，引入会从 `#entry` 开始。这意味着入口文件的变更不会使其他未变更的代码块失效。

::note
当你配置了 `vite.build.target` 包含不支持导入映射的浏览器，或配置了不含 `[hash]` 的 `vite.build.rollupOptions.output.entryFileNames` 时，Nuxt 会智能禁用此功能。
::

如果需要禁用此功能，可以这样设置：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // 或者，最好是直接告诉 vite 你想要的目标环境
  // Nuxt 会尊重该配置
  vite: {
    build: {
      target: 'safari13',
    },
  },
})
```

## typescriptPlugin

启用使用 `@dxup/nuxt` 模块，提升 TypeScript 开发体验。

该实验性插件提供更好的 TypeScript 集成和开发工具，改善在 Nuxt 应用中使用 TypeScript 的开发体验。

默认禁用，你可以启用：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true,
  },
})
```

::important
使用此功能需要：

- 安装 `typescript` 作为依赖
- 将 VS Code 配置为使用工作区的 TypeScript 版本（参见 [VS Code 文档](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript)）
::

::read-more{icon="i-simple-icons-github" to="https://github.com/KazariEX/dxup" target="_blank"}
了解更多 **@dxup/nuxt**。
::

## viteEnvironmentApi

启用 Vite 6 新的[环境 API](https://vite.dev/guide/api-environment)，以改善构建配置和插件架构。

当你将 `future.compatibilityVersion` 设为 `5` 时，该功能默认启用，也可显式开启用于测试：

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true,
  },
})
```

Vite 环境 API 提供更一致的开发和生产构建体验，更细粒度的环境相关配置控制，以及更好的性能。

::important
启用此功能会改变 Vite 插件的注册和配置方式。有关更新插件的详细信息，请参阅 [Vite 环境 API 迁移指南](https://nuxt.com/docs/5.x/getting-started/upgrade#migration-to-vite-environment-api)。
::

::read-more{to="https://vite.dev/guide/api-environment" target="_blank"}
了解更多 Vite 环境 API。
::


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.