自動匯入 · 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/ 匯出的函式和變數。

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

內建自動匯入

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 setup 函式之外使用它們。最重要的是，您必須同步使用它們 - 也就是說，除了在 <script setup> 區塊中、在用 defineNuxtComponent 宣告的元件的 setup 函式中、在 defineNuxtPlugin 或 defineNuxtRouteMiddleware 中之外，您不能在呼叫組合式函式之前使用 await，在這些情況下，我們會執行轉換以保持同步上下文，即使在 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 如何處理非模板頂層的 refs。您可以在 Vue 文件中閱讀更多相關資訊。

顯式匯入

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

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

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

停用自動匯入

如果您想停用自動匯入組合式函式和工具程式，您可以將 imports.autoImport 設定為 nuxt.config 檔案中的 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 友善的使用方式。