實驗性功能

Nuxt 包含實驗性功能，您可以在配置檔案中啟用它們。

在內部，Nuxt 使用 @nuxt/schema 來定義這些實驗性功能。您可以參考 API 文件 或原始碼獲取更多資訊。

alwaysRunFetchOnKeyChange

當鍵發生變化時是否執行 useFetch，即使它設定為 immediate: false 並且尚未觸發。

如果 immediate: true 或已觸發，useFetch 和 useAsyncData 將始終在鍵更改時執行。

此標誌預設停用，但您可以啟用此功能。

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

appManifest

使用應用程式清單來在客戶端遵守路由規則。

此標誌預設啟用，但您可以停用此功能。

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

asyncContext

在 Nuxt 和 Nitro 中啟用原生非同步上下文，以供巢狀的 composable 訪問。這使得在非同步 composable 中使用 composable 成為可能，並減少出現 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: false,
  },
})

extractAsyncDataHandlers

從 useAsyncData 和 useLazyAsyncData 呼叫中提取處理程式函式到單獨的 chunk 中，以改進程式碼分割和快取效率。

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

此功能將內聯處理程式函式轉換為動態匯入的 chunk。

<!-- 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 chunk 時發生錯誤時，發出 app:chunkError 鉤子。預設行為是在導航到新路由時，如果 chunk 載入失敗，則執行新路由的重新載入。

預設情況下，當導航到新路由時，如果 chunk 載入失敗，Nuxt 也會執行新路由的重新載入（automatic）。

將此設定為 automatic-immediate 將導致 Nuxt 在 chunk 載入失敗時立即執行當前路由的重新載入（而不是等待導航）。這對於不是由導航觸發的 chunk 錯誤很有用，例如，當您的 Nuxt 應用程式無法載入 懶載入元件 時。這種行為的潛在缺點是意外的重新載入，例如，當您的應用程式不需要導致錯誤的 chunk 時。

您可以透過將其設定為 false 來停用自動處理，或者透過將其設定為 manual 來手動處理 chunk 錯誤。

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

enforceModuleCompatibility

如果 Nuxt 模組不相容，Nuxt 是否應該丟擲錯誤（並載入失敗）。

此功能預設停用。

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

restoreState

允許在 chunk 錯誤或手動呼叫 reloadNuxtApp() 後重新載入頁面時，從 sessionStorage 恢復 Nuxt 應用程式狀態。

為避免水合錯誤，它只會在 Vue 應用程式掛載後應用，這意味著在初始載入時可能會出現閃爍。

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

inlineRouteRules

使用 defineRouteRules 在頁面級別定義路由規則。

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

將根據頁面的 path 建立匹配的路由規則。

renderJsonPayloads

允許渲染 JSON 有效負載，並支援恢復複雜型別。

此標誌預設啟用，但您可以停用此功能。

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

noVueServer

停用 Nitro 中的 Vue 伺服器渲染器端點。

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

parseErrorData

渲染伺服器錯誤頁面時是否解析 error.data。

此標誌預設啟用，但您可以停用此功能。

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

payloadExtraction

啟用使用 nuxt generate 生成的頁面的有效負載提取。

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

clientFallback

啟用實驗性的 <NuxtClientFallback> 元件，用於在 SSR 出現錯誤時在客戶端渲染內容。

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

crossOriginPrefetch

使用推測規則 API 啟用跨域預取。

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

viewTransition

啟用檢視轉換 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'
  },
})

localLayerAliases

根據其層源和根目錄解析層中 ~、~~、@ 和 @@ 別名。

此標誌預設啟用，但您可以停用此功能。

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

typedPages

使用新的實驗性型別化路由器。unplugin-vue-router.

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

開箱即用，這將啟用 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' or 'parcel' are also options
  },
})

sharedPrerenderData

Nuxt 自動在預渲染頁面之間共享有效負載 _資料_。當預渲染的站點在不同頁面中使用 useAsyncData 或 useFetch 並獲取相同資料時，這可以顯著提高效能。

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

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

啟用此功能時，特別重要的是要確保您的資料的任何唯一鍵始終解析為相同的資料。例如，如果您使用 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 在客戶端構建中自動填充 Node.js 匯入。unenv.

import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer

scanPageMeta

Nuxt 在構建時向模組公開在 definePageMeta 中定義的一些路由元資料（特別是 alias、name、path、redirect、props 和 middleware）。

這僅適用於靜態或字串/陣列，而不適用於變數或條件賦值。請參閱原始問題以獲取更多資訊和上下文。

預設情況下，頁面元資料僅在所有路由在 pages:extend 中註冊後才進行掃描。然後會呼叫另一個鉤子 pages:resolved。

如果此功能在您的專案中引起問題，您可以停用它。

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

cookieStore

啟用 CookieStore 支援以監聽 cookie 更新（如果瀏覽器支援）並重新整理 useCookie 引用值。

此標誌預設啟用，但您可以停用此功能。

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

buildCache

根據配置和原始檔的雜湊值快取 Nuxt 構建工件。

這僅適用於應用程式的 Vue/Nitro 部分中 srcDir 和 serverDir 內的原始檔。

此標誌預設停用，但您可以啟用它。

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 宣佈其可快取工件及其雜湊值）。

checkOutdatedBuildInterval

設定檢查新構建的時間間隔（毫秒）。當 experimental.appManifest 為 false 時停用。

設定為 false 可停用。

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。

此標誌預設啟用，但您可以停用此功能。

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

normalizeComponentNames

Nuxt 更新自動生成的 Vue 元件名稱，以匹配您用於自動匯入元件的完整元件名稱。

如果遇到問題，您可以停用此功能。

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 鉤子的效能標記。這會新增效能標記，您可以在基於 Chromium 的瀏覽器的效能選項卡中跟蹤這些標記，這對於除錯和最佳化效能很有用。

此功能在開發模式下預設啟用。如果您需要停用此功能，可以這樣做。

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

debugModuleMutation

在模組上下文中記錄對 nuxt.options 的修改，有助於除錯 Nuxt 初始化階段模組所做的配置更改。

當啟用 debug 模式時，此功能預設啟用。如果您需要停用此功能，可以這樣做。

要明確啟用它：

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

lazyHydration

這啟用了 <Lazy> 元件的水合策略，透過延遲元件的水合直到需要時才進行，從而提高效能。

懶惰水合預設啟用，但您可以停用此功能。

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

templateImportResolution

停用從新增模板的模組路徑解析匯入到 Nuxt 模板中。

預設情況下，Nuxt 嘗試根據新增模板的模組解析模板中的匯入。將其設定為 false 將停用此行為，這在某些環境中遇到解析衝突時可能很有用。

此標誌預設啟用，但您可以停用此功能。

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

templateRouteInjection

預設情況下，由自動匯入的 useRoute() 可組合函式返回的路由物件與 <NuxtPage> 中當前顯示的頁面保持同步。對於 vue-router 匯出的 useRoute 或 Vue 模板中可用的預設 $route 物件，情況並非如此。

透過啟用此選項，將注入一個 mixin 以使 $route 模板物件與 Nuxt 管理的 useRoute() 保持同步。

此標誌預設啟用，但您可以停用此功能。

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

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'

defaults

這允許為核心 Nuxt 元件和可組合項指定預設選項。

這些選項未來可能會移動到其他地方，例如 app.config 或 app/ 目錄。

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

purgeCachedData

是否在路由導航時清除 Nuxt 靜態和 asyncData 快取。

Nuxt 將自動清除 useAsyncData 和 nuxtApp.static.data 中的快取資料。這有助於防止記憶體洩漏並確保在需要時載入最新資料，但可以停用它。

此標誌預設啟用，但您可以停用此功能。

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

granularCachedData

在重新整理 useAsyncData 和 useFetch 的資料時（無論是透過 watch、refreshNuxtData() 還是手動 refresh() 呼叫），是否呼叫並使用 getCachedData 的結果。

此標誌預設啟用，但您可以停用此功能。

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

headNext

使用頭部最佳化

• 新增 capo.js 頭部外掛，以更高效的方式渲染頭部中的標籤。
• 使用雜湊水合外掛減少初始水合。

此標誌預設啟用，但您可以停用此功能。

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

pendingWhenIdle

對於 useAsyncData 和 useFetch，當資料尚未開始獲取時，pending 是否應為 true。

此標誌預設停用，但您可以啟用此功能。

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

entryImportMap

預設情況下，Nuxt 透過使用匯入對映來解析包的入口 chunk，從而提高 chunk 穩定性。

這將在您的 <head> 標籤頂部注入一個匯入對映。

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

在 Vite 發出的指令碼塊中，匯入將來自 #entry。這意味著對入口的更改不會使其他未更改的塊失效。

如果您需要停用此功能，可以這樣做。

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 開發體驗。

這個實驗性外掛提供了改進的 TypeScript 整合和開發工具，以在使用 Nuxt 應用程式中的 TypeScript 時提供更好的開發體驗。

此標誌預設停用，但您可以啟用此功能。

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