實驗性功能
Nuxt 實驗性功能可以在 Nuxt 設定檔中啟用。
在內部，Nuxt 使用 @nuxt/schema 來定義這些實驗性功能。您可以參考 API 文件或 原始碼以取得更多資訊。
asyncContext
啟用原生非同步上下文，以便在 Nuxt 和 Nitro 中存取巢狀 composables。這開啟了在非同步 composables 內部使用 composables 的可能性，並減少出現 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
}
})
treeshakeClientOnly
從伺服器套件中移除僅限客戶端元件的內容。
預設為啟用。
export default defineNuxtConfig({
experimental: {
treeshakeClientOnly: true
}
})
emitRouteChunkError
當載入 vite/webpack 區塊時發生錯誤時，發出 app:chunkError 鉤子。預設行為是在導航到新路由時，當區塊載入失敗時執行新路由的重新載入。
如果您將此設定為 'automatic-immediate'，Nuxt 會立即重新載入目前的路由，而不是等待導航。這對於並非由導航觸發的區塊錯誤很有用，例如，當您的 Nuxt 應用程式無法載入 延遲載入元件時。此行為的一個潛在缺點是不必要的重新載入，例如，當您的應用程式不需要導致錯誤的區塊時。
您可以將此設定為 false 來停用自動處理，或將其設定為 manual 來手動處理區塊錯誤。
export default defineNuxtConfig({
experimental: {
emitRouteChunkError: 'automatic' // or 'automatic-immediate', 'manual' or 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
使用推測規則 API 啟用跨來源預先提取。
export default defineNuxtConfig({
experimental: {
crossOriginPrefetch: true
}
})
viewTransition
啟用 View Transition API 與用戶端路由器整合。
export default defineNuxtConfig({
experimental: {
viewTransition: true
}
})
writeEarlyHints
在使用節點伺服器時啟用早期提示的寫入。
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) 內的 ~、~~、@ 和 @@ 別名，使其對應到它們的層來源和根目錄。
預設為啟用。
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') 在頁面中取得類型化的參數。
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
啟用此功能會在預先渲染的頁面之間自動共享 payload data。當預先渲染使用 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 在客戶端建置中自動填充 Node.js 匯入。
Buffer 這樣的全域變數在瀏覽器中運作，您需要手動注入它們。import { Buffer } from 'node:buffer'
globalThis.Buffer = globalThis.Buffer || Buffer
scanPageMeta
此選項允許在建置時將 definePageMeta 中定義的一些路由元資料暴露給模組（特別是 alias、name、path、redirect）。
這僅適用於靜態或字串/陣列，而不適用於變數或條件賦值。 有關更多資訊和背景資訊，請參閱原始問題。
也可以在所有路由都在 pages:extend 中註冊後才掃描頁面元數據。然後會調用另一個 hook 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 客戶端/伺服器套件的重建。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 開發者工具中識別它，則需要使用此組件。
但是，為了自動匯入它，您需要使用 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 -->
這可以避免在水合作用僅限客戶端的頁面時出現白屏閃爍。