ViteMigration GuideBuild ToolingFrontend Engineering

Vite 6 升級指南：Vite 5 遷移清單與風險檢查

給仍在 Vite 5 的團隊：整理 Vite 6 migration guide 重點，含 Node.js 版本邊界、插件升級與 Vite 7/8 差異，降低升版風險。

· 4 分鐘閱讀
📋 目錄

這篇會幫你把 Vite 6 的官方變更拆成「必做」「可能要做」「不用現在做」，避免把 Vite 7/8 的資訊誤當成 Vite 6 需求。

前言

很多團隊在看 Vite 升級資訊時，會把 Vite 6、Vite 7、Vite 8 的內容混在一起，最後變成「不知道該不該升」。最常見的錯誤包含：把 build.target Baseline 的預設切換當成 Vite 6 變更、把 Rolldown 當成 Vite 6 已經全面落地、或是把 plugin 套件名寫錯成 vite-plugin-react 這類不存在的官方套件。

如果你目前是 Vite 5，這次升級其實不一定痛。Vite 6 的官方目標是盡量減少 breaking change，讓多數應用可以快速升版；真正受影響最多的是 framework authors 或深度客製 plugin/tooling 的團隊。

本文以 2026-04-01 可核對資訊為準（vite 最新 8.0.3、vite@6 最新 6.4.1），聚焦在「你現在要不要從 Vite 5 升 Vite 6」這個決策。

這篇適合誰讀

如果你符合以下任一情境，這篇會直接有用：

  • 目前仍在 Vite 5，想判斷是否該升 Vite 6
  • 維護 React/Vue/Svelte 等一般 SPA 專案，想知道升級是否需要改程式
  • 維護 framework/plugin/tooling，想掌握 Vite 6 真正有影響的 migration 點
  • 正在規劃未來 Vite 7/8，但不想在 Vite 6 階段做過度改造

Vite 6 真正的重要變更

1. Node.js 支援範圍（Vite 6）

Vite 6 支援 Node.js 18、20、22+，並移除 Node.js 21。
如果你的團隊還有機器卡在 Node 21，這是升級前第一個必修正項目。

# 建議在本機與 CI 都先確認
node -v

2. Environment API（experimental）

Vite 6 這次最核心的新能力是 Environment API，但主要受眾是 framework authors。
如果你是一般 SPA 使用者，官方明確表示「多數情境不用改」。

3. migration guide 裡的「一般變更」

這些才是 Vite 5 -> Vite 6 真正常見會遇到的點：

  • resolve.conditions / ssr.resolve.conditions 預設行為調整
  • json.stringify 預設變成 'auto'（大 JSON 才自動 stringify）
  • Sass 改用 modern API（legacy API 之後版本會完全移除）
  • postcss-load-config 升級（TS/YAML config 可能要補套件）
  • library mode 可自訂 CSS 輸出檔名（build.lib.cssFileName）

如果你有自訂 resolve.conditions，請用 Vite 匯出的預設常數擴充，不要自己硬編完整陣列：

import { defineConfig } from 'vite'
import { defaultClientConditions, defaultServerConditions } from 'vite'

export default defineConfig({
  resolve: {
    // 保留 Vite 6 預設，再加入自訂條件
    conditions: ['custom-condition', ...defaultClientConditions],
  },
  ssr: {
    resolve: {
      conditions: ['custom-ssr-condition', ...defaultServerConditions],
    },
  }
})

實際 migration checklist（Vite 5 -> Vite 6）

Step 1：先卡死 runtime 與套件版本

# 1) 確認 Node 版本在 Vite 6 支援範圍
node -v

# 2) 安裝 Vite 6
pnpm add -D vite@^6

# 3) 升級官方插件（注意是 @vitejs scope）
pnpm add -D @vitejs/plugin-react@latest
pnpm add -D @vitejs/plugin-vue@latest

重點是套件名：請用 @vitejs/plugin-react、@vitejs/plugin-vue，不要寫成 vite-plugin-react / vite-plugin-vue。

Step 2：檢查你是否有「非預設」設定

如果你完全使用預設值，多數專案升版後就能跑。
真正要逐條比對 migration guide 的，通常是這些情境：

  • 你自訂過 resolve.conditions 或 SSR resolve 行為
  • 你有大量 JSON 匯入，且曾依賴舊的 stringify 行為
  • 你使用 Sass legacy API
  • 你是 library mode 且引用固定 style.css 檔名

Step 3：跑最小可用驗證腳本

pnpm run dev
pnpm run build
pnpm run preview
pnpm run test

建議把升級驗證固定成一條腳本，避免靠人工流程遺漏：

{
  "scripts": {
    "verify:vite6-upgrade": "pnpm run typecheck && pnpm run test && pnpm run build"
  }
}

哪些是 ecosystem future，不該當成 Vite 6 已落地能力

這段是避免決策誤差的關鍵：

  1. build.target 預設改成 baseline-widely-available，是 Vite 7 的 migration 脈絡，不是 Vite 6。
  2. Node.js 需要 20.19+ / 22.12+，也是 Vite 7 之後的要求，不是 Vite 6。
  3. Rolldown/Oxc 的更深整合，是 Vite 7/8 期間逐步演進，不等於 Vite 6 已全面切換。

如果你現在只是要把 Vite 5 升到 Vite 6，不需要一次把後續 major 的工程成本提前吞下去。

常見問題 / 注意事項

Q1：一般 SPA 升到 Vite 6 需要改很多程式碼嗎？

多數不需要。只要不是深度客製 config 或 framework/tooling 層，通常升版與驗證即可。

Q2：我需要立刻研究 Environment API 嗎？

若你是應用層團隊，可先不用。這個 API 主要是給 framework authors 與底層工具作者。

Q3：Node 18 還能用在 Vite 6 嗎？

在 Vite 6 時代可以，但若你接下來會升 Vite 7+，就應提前規劃升到 Node 20/22 LTS，避免下一次升級卡 runtime。

總結

Vite 6 升級的正確心法是：先把問題定義成「Vite 5 -> Vite 6 的最小風險遷移」，而不是把整個 Vite 生態未來路線一次打包。

你可以用這個判斷：

  • 現在就升：目前在 Vite 5、Node 版本符合、插件相容，且希望維持工具鏈在受支持區間。
  • 先做小規模試點：有客製 SSR/resolve 行為或 library mode 特殊輸出需求。
  • 暫緩但排期：runtime 與 CI 版本分裂嚴重，還沒辦法穩定驗證。

把升級做成可回滾、可量測、可重複執行的流程，比追版本號更重要。

參考資料