1. Nuxt 的自動魔法

您可以把 Nuxt 想像成一位智慧管家。

當您啟動專案時，這位管家會檢查您的專案結構，然後在 .nuxt/ 資料夾裡，自動產生好幾份為您量身打造的、最優化的 tsconfig 設定檔。這些設定檔包含了所有路徑別名（例如 ~/composables、#imports）和 TypeScript 的最佳實踐。

智慧管家的工作

自動分析專案結構

生成最優化的 TypeScript 設定

設定路徑別名和自動導入

應用 TypeScript 最佳實踐

自動生成的設定檔

.nuxt/tsconfig.app.json

.nuxt/tsconfig.server.json

.nuxt/tsconfig.json

包含的功能

路徑別名設定

型別定義匯入

編譯器選項優化

2. 我們唯一要做的事

既然管家都把事情做好了，我們唯一需要做的，就是在專案的根目錄建立一個 tsconfig.json 檔案，然後告訴我們的編輯器（例如 VS Code）去參考管家產生好的那些檔案。

這個檔案的內容通常都是固定的，直接複製貼上即可：

tsconfig.json

// tsconfig.json
{
  // "references" 就像是「請參考以下這些由 Nuxt 產生的設定檔」
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" }
  ]
}

注意

一個新的 Nuxt 專案在初始化時，通常就已經幫您建立好這個檔案了。

這樣做之後，您的 VS Code 就能讀懂 Nuxt 的所有魔法，提供正確的型別檢查和路徑自動補全，讓您的開發體驗大幅提升。

✅ 獲得的好處

智慧型別檢查

路徑自動補全

import 語句提示

即時錯誤偵測

🎯 編輯器支援

VS Code 完整支援

WebStorm 智慧提示

Vim/Neovim 整合

其他 LSP 編輯器

3. 兩個「不要」

❌ 不要手動修改自動生成的檔案

不要手動修改 .nuxt/ 裡的 tsconfig 檔案，因為它們是自動產生的，您的修改會在下次啟動專案時被覆蓋。

❌ 不要在根目錄的 tsconfig.json 添加設定

如果需要新增自訂的路徑別名，不要直接寫在您根目錄的 tsconfig.json 裡。請到 nuxt.config.ts 的 alias 屬性中去設定，這樣 Nuxt 管家才能知道，並幫您加到自動產生的設定檔中。

正確的做法

// nuxt.config.ts
export default defineNuxtConfig({
  alias: {
    '@components': './components'
  }
})

為什麼要這樣做？

這樣做可以確保您的自訂設定能正確地被 Nuxt 的智慧管家識別，並整合到自動生成的 TypeScript 設定中，避免設定衝突和不一致的問題。

今日總結

tsconfig.json 在 Nuxt 專案中的角色更像是一個「指路牌」，而不是一個需要我們費心設定的檔案。

Nuxt 會自動生成最優化的 TypeScript 設定檔。

我們只需要建立指路牌，引用自動生成的設定。

不要手動修改 .nuxt/ 目錄下的任何檔案。

自訂設定應該在 nuxt.config.ts 中進行。

結語

我們只需要建立好這個指路牌，剩下的複雜設定就安心交給 Nuxt 這位智慧管家來處理吧！至此，我們已經完成了對 Nuxt 主要資料夾與設定檔的全面探索！