Next.js static export

部署
Next.js 靜態網站

把 Next.js app 匯出成靜態 HTML 和資源檔，上傳 out 目錄，不需要執行 Node.js 伺服器也能全球發佈。

查看設定指南
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
// Optional for static deployments
images: { unoptimized: true },
}

module.exports = nextConfig
已啟用靜態匯出

Static export 支援矩陣

上傳 out 前，先確認 app 符合靜態匯出模型。

適合

  • 建置時產生的靜態路由
  • 可靜態渲染的 App Router 頁面
  • Pages Router getStaticProps / getStaticPaths
  • Hydration 後的 client-side data fetching
  • next/link、dynamic imports、CSS Modules 和靜態資源

需要其他 runtime

  • 需要伺服器執行的 API routes 和 route handlers
  • Middleware、rewrites、redirects 和自訂 headers
  • getServerSideProps 與 request-time rendering
  • Incremental Static Regeneration
  • 沒有自訂靜態策略的預設 next/image optimization

需要框架能力，但不需要伺服器時使用 Next.js

保留框架，拿掉伺服器

Next.js static export 讓你保留檔案式路由、layout、metadata、build-time rendering、CSS 支援，以及需要時的 client-side React。

輸出結果仍然只是檔案。這很適合行銷頁、文件站、作品集、產品頁、內容中心，以及能在建置時準備好的頁面。

像靜態資源一樣快

預先產生的 HTML 可以積極快取，並直接從邊緣節點提供，不必等待伺服器即時 render。

維運負擔更少

沒有 Node runtime，代表生產環境需要維護的環節更少，部署產物也更清楚。

執行邊界清楚

需要伺服器程式碼的頁面不該硬做成 static export。能提前建置的頁面，out 目錄就是乾淨的發佈產物。

常見 static export 阻礙

Blocker 01

因 server-only 功能導致建置失敗

從匯出路由移除 request-time API，把邏輯移到獨立後端，或把該部分部署到支援伺服器功能的平台。

Blocker 02

圖片在開發環境正常，匯出後失效

預設 next/image optimizer 需要伺服器。請使用 images.unoptimized、自訂 loader，或一般靜態圖片資源。

Blocker 03

動態路由缺頁

在 App Router 用 generateStaticParams，或在 Pages Router 用 getStaticPaths，在建置時產生路由清單。

Blocker 04

Redirects 或 rewrites 沒有套用

Next.js redirects 和 rewrites 不屬於 static export。請使用靜態頁結構、client-side navigation，或可用的平台層 redirect。

Next.js 靜態匯出檢查表

01

設定 output: 'export'

讓 Next.js 在建置時輸出靜態 HTML，而不是期待 next start 或 Node runtime。

output: 'export'
02

建置並檢查 /out

執行正式 build，確認 out 目錄包含要發佈的頁面、資源、404 頁和靜態檔案。

npm run build
03

上傳並測試路由

上傳 out 目錄後，檢查深層路徑、靜態資源和未最佳化圖片是否在上線網站正常。

Next.js 部署常見問題

為什麼 Next.js Image 元件匯出後會壞掉？

預設 Image 最佳化流程需要伺服器。靜態匯出時，請在 next.config.js 設定 images.unoptimized 為 true。

API routes 或 getServerSideProps 可以在這裡用嗎？

不行。Static export 會移除 API routes、middleware、getServerSideProps 等伺服器端 runtime 功能。請把這些邏輯移到獨立後端或 serverless 服務。

可以使用 App Router 嗎？

可以，只要該路由可靜態渲染，且不依賴 headers、cookies 等 dynamic server-only API。

動態內容該怎麼處理？

能在建置時取得就先建置；否則在頁面 hydration 後由 client-side 載入。Static export 最適合 HTML 可提前準備的頁面。

應該上傳 .next 還是 out？

output: 'export' 要上傳 out。.next 是 Next.js 的內部建置目錄，不是你要發佈的靜態匯出產物。

這能取代 Vercel 的 Next.js hosting 嗎？

它適合靜態匯出，不適合每一種 Next.js app。如果你依賴 SSR、middleware、ISR、server actions 或 API routes，就需要支援這些功能的 runtime。