2026-04-28
Nuxt 3 → 4 升級實戰：8 個你會踩到的雷
從 Nuxt 3.13 一路升到 4.4.6，看似只是 major bump，但在 Vite 7、ESLint 9 與 flat config 之間其實有不少地雷。
升級過程中我們紀錄了 8 個主要踩雷點，包含：1) `@nuxt/devtools` 重複登錄、2) `vue-tsc` 與 TypeScript 5 的 peer dep 衝突、3) `nuxt-security` schema v0 → v2 的 breaking change、4) `vite-plugin-svg-icons` 的 ESM 改名、5) prerender 對動態 route 的處理變嚴格、6) ScrollTrigger 在 ssr: true 時的初始化時序、7) Lenis 的 page:finish hook 順序、8) `defineCachedEventHandler` 的 swr 設定差異。
每個我們都附了 reproducible 的最小範例與修法。建議升級時不要一次跳兩個 major。
