自動導入 · Nuxt 概念

Nuxt 會自動導入元件、組合式函式和 Vue.js API，以便在您的應用程式中使用，而無需明確導入它們。

app.vue

<script setup lang="ts">
const count
 = ref
(1) // ref is auto-imported
</script>

由於其有主見的目錄結構，Nuxt 可以自動導入您的 components/、composables/ 和 utils/。

與傳統的全局宣告相反，Nuxt 保留了類型，IDE 完成和提示，並且僅包含您的生產程式碼中使用的內容。

在文件中，每個未明確導入的函式都由 Nuxt 自動導入，並且可以在您的程式碼中直接使用。您可以在 API 區段中找到自動導入的元件、組合式函式和工具程式的參考資料。

在 server 目錄中，Nuxt 會自動導入從 server/utils/ 匯出的函式和變數。

您還可以透過設定 nuxt.config 檔案的 imports 區段，自動導入從自訂資料夾或第三方套件匯出的函式。

內建自動導入

Nuxt 自動導入函式和組合式函式來執行資料獲取、存取應用程式內容和執行階段設定、管理狀態或定義元件和外掛程式。

<script setup lang="ts">
/* useFetch() is auto-imported */
const { data
, refresh
, status
 } = await useFetch
('/api/hello')
</script>

Vue 3 公開了響應性 API，例如 ref 或 computed，以及由 Nuxt 自動導入的生命週期鉤子和輔助函式。

<script setup lang="ts">
/* ref() and computed() are auto-imported */
const count
 = ref
(1)
const double
 = computed
(() => count
.value
 * 2)
</script>

Vue 和 Nuxt 組合式函式

當您使用 Vue 和 Nuxt 提供的內建 Composition API 組合式函式時，請注意它們中的許多函式都依賴於在正確的上下文中調用。

在元件的生命週期中，Vue 會透過全域變數追蹤目前元件的暫時執行個體（同樣，Nuxt 會追蹤 nuxtApp 的暫時執行個體），然後在同一刻取消設定。這在伺服器端渲染時至關重要，既可以避免跨請求狀態污染（在兩個使用者之間洩漏共享的參考），又可以避免不同元件之間的洩漏。

這意味著（除了極少數例外情況），您不能在 Nuxt 外掛程式、Nuxt 路由中介軟體或 Vue 設定函式之外使用它們。最重要的是，您必須同步使用它們 - 也就是說，您不能在調用組合式函式之前使用 await，除非在 <script setup> 區塊、使用 defineNuxtComponent 宣告的元件的設定函式中、在 defineNuxtPlugin 中或在 defineNuxtRouteMiddleware 中，在這些地方我們會執行轉換以在 await 之後保持同步上下文。

如果您收到類似 Nuxt instance is unavailable 的錯誤訊息，則可能表示您在 Vue 或 Nuxt 生命週期中的錯誤位置調用了 Nuxt 組合式函式。

觀看 Alexander Lichter 關於處理組合式函式中的非同步程式碼並修復應用程式中 Nuxt instance is unavailable 的影片。

當在非 SFC 元件內使用需要 Nuxt 上下文的組合式函式時，您需要使用 defineNuxtComponent 而不是 defineComponent 來包裝您的元件

查看 asyncContext 實驗性功能，以便在非同步函式中使用 Nuxt 組合式函式。

請參閱此 GitHub 評論中的完整說明。

損壞程式碼的範例

composables/example.ts

// trying to access runtime config outside a composable
const config
 = useRuntimeConfig
()

export const useMyComposable
 = () => {
  // accessing runtime config here
}

運作程式碼的範例

composables/example.ts

export const useMyComposable
 = () => {
  // Because your composable is called in the right place in the lifecycle,
  // useRuntimeConfig will work here
  const config
 = useRuntimeConfig
()

  // ...
}

基於目錄的自動導入

Nuxt 會直接自動導入在已定義目錄中建立的檔案

components/ 用於 Vue 元件。
composables/ 用於 Vue 組合式函式。
utils/ 用於輔助函式和其他工具程式。

在文件 > 範例 > 功能 > 自動導入中讀取和編輯即時範例。

自動導入的 ref 和 computed 在元件的 <template> 中不會被解包。
這是因為 Vue 處理非模板頂層 ref 的方式。您可以在 Vue 文件中閱讀更多相關資訊。

顯式導入

Nuxt 使用 #imports 別名公開每個自動導入，如果需要，可以使用它來進行顯式導入。

<script setup lang="ts">
import { ref, computed } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>

停用自動導入

如果您想停用自動導入組合式函式和工具，可以在 nuxt.config 檔案中將 imports.autoImport 設定為 false。

nuxt.config.ts

export default defineNuxtConfig
({
  imports
: {
    autoImport
: false
  }
})

這將完全停用自動導入，但仍然可以從 #imports 使用顯式導入。

部分停用自動導入

如果您希望像 ref 這樣的框架特定函式保持自動導入，但希望停用您自己程式碼（例如，自訂組合式函式）的自動導入，您可以在 nuxt.config.ts 檔案中將 imports.scan 選項設定為 false。

export default defineNuxtConfig({
  imports: {
    scan: false
  }
})

使用此配置

像 ref、computed 或 watch 這樣的框架函式仍可在無需手動導入的情況下運作。
自訂程式碼（例如組合式函式）將需要手動導入到您的檔案中。

注意：此設定有一些限制

如果您的專案結構包含層級，您將需要顯式從每個層級導入組合式函式，而不是依賴自動導入。
這會破壞層級系統的覆寫功能。如果您使用 imports.scan: false，請確保您了解此副作用並相應調整您的架構。

自動導入元件

Nuxt 還會自動導入您 ~/components 目錄中的元件，儘管這與自動導入組合式函式和實用函式的配置是分開的。

在文件 > 指南 > 目錄結構 > 元件中閱讀更多相關資訊。

若要停用從您自己的 ~/components 目錄自動導入元件，您可以將 components.dirs 設定為空陣列（但請注意，這不會影響模組新增的元件）。

nuxt.config.ts

export default defineNuxtConfig
({
  components
: {
    dirs
: []
  }
})

從第三方套件自動導入

Nuxt 也允許從第三方套件自動導入。

如果您正在使用該套件的 Nuxt 模組，則該模組很可能已經為該套件設定了自動導入。

例如，您可以像這樣啟用從 vue-i18n 套件自動導入 useI18n 組合式函式

nuxt.config.ts

export default defineNuxtConfig
({
  imports
: {
    presets
: [
      {
        from
: 'vue-i18n',
        imports
: ['useI18n']
      }
    ]
  }
})

觀看 Alexander Lichter 的影片，了解如何輕鬆設定自訂自動導入。

升級指南

了解如何升級到最新的 Nuxt 版本。

Vue.js 開發

Nuxt 使用 Vue.js，並新增了元件自動導入、基於檔案的路徑和 SSR 友善使用的組合式函式等功能。