靜態匯出 (Static Exports)

Next.js 允許您從靜態網站或單頁應用程式 (SPA) 開始，之後可選擇升級使用需要伺服器的功能。

當執行 next build 時，Next.js 會為每個路由生成一個 HTML 檔案。透過將嚴格的 SPA 拆分成獨立的 HTML 檔案，Next.js 可以避免在客戶端載入不必要的 JavaScript 程式碼，減少套件大小並實現更快的頁面載入速度。

由於 Next.js 支援這種靜態匯出，因此可以部署並託管在任何能夠提供 HTML/CSS/JS 靜態資源的網頁伺服器上。

設定

要啟用靜態匯出，請在 next.config.js 中更改輸出模式：

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  output: 'export',

  // 選項：將連結 `/me` 改為 `/me/` 並產生 `/me.html` -> `/me/index.html`
  // trailingSlash: true,

  // 選項：防止自動將 `/me` 轉為 `/me/`，保留原始 `href`
  // skipTrailingSlashRedirect: true,

  // 選項：更改輸出目錄 `out` -> `dist`
  // distDir: 'dist',
}

module.exports = nextConfig

執行 next build 後，Next.js 會產生一個 out 資料夾，其中包含應用程式的 HTML/CSS/JS 資源。

支援的功能

Next.js 的核心設計支援靜態匯出。

伺服器元件 (Server Components)

當您執行 next build 生成靜態匯出時，app 目錄中的伺服器元件會在構建期間執行，類似於傳統的靜態網站生成 (SSG)。

產生的元件將被渲染為初始頁面載入的靜態 HTML 和路由間客戶端導航的靜態 payload。使用靜態匯出時，除非它們使用動態伺服器功能，否則您的伺服器元件不需要任何更改。

export default async function Page() {
  // 這個 fetch 會在 `next build` 期間在伺服器上執行
  const res = await fetch('https://api.example.com/...')
  const data = await res.json()

  return <main>...</main>
}

客戶端元件 (Client Components)

如果您想在客戶端執行資料獲取，可以使用客戶端元件搭配 SWR 來快取請求。

'use client'

import useSWR from 'swr'

const fetcher = (url: string) => fetch(url).then((r) => r.json())

export default function Page() {
  const { data, error } = useSWR(
    `https://jsonplaceholder.typicode.com/posts/1`,
    fetcher
  )
  if (error) return '載入失敗'
  if (!data) return '載入中...'

  return data.title
}

由於路由轉換發生在客戶端，這行為類似於傳統的 SPA。例如，以下索引路由允許您在客戶端導航到不同的文章：

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>索引頁面</h1>
      <hr />
      <ul>
        <li>
          <Link href="/post/1">文章 1</Link>
        </li>
        <li>
          <Link href="/post/2">文章 2</Link>
        </li>
      </ul>
    </>
  )
}

圖片優化 (Image Optimization)

透過在 next.config.js 中定義自訂圖片載入器，可以在靜態匯出中使用 next/image 的圖片優化功能。例如，您可以使用 Cloudinary 等服務優化圖片：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './my-loader.ts',
  },
}

module.exports = nextConfig

這個自訂載入器將定義如何從遠端來源獲取圖片。例如，以下載入器將為 Cloudinary 構建 URL：

export default function cloudinaryLoader({
  src,
  width,
  quality,
}: {
  src: string
  width: number
  quality?: number
}) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
  return `https://res.cloudinary.com/demo/image/upload/${params.join(
    ','
  )}${src}`
}

然後您可以在應用程式中使用 next/image，定義 Cloudinary 中圖片的相對路徑：

import Image from 'next/image'

export default function Page() {
  return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}

路由處理器 (Route Handlers)

執行 next build 時，路由處理器 (Route Handlers) 會渲染靜態回應。僅支援 GET HTTP 方法。這可用於從快取或非快取資料生成靜態 HTML、JSON、TXT 或其他檔案。例如：

export async function GET() {
  return Response.json({ name: 'Lee' })
}

上述檔案 app/data.json/route.ts 將在 next build 期間渲染為靜態檔案，產生包含 { name: 'Lee' } 的 data.json。

如果您需要從傳入請求中讀取動態值，則無法使用靜態匯出。

瀏覽器 API (Browser APIs)

客戶端元件在 next build 期間會預渲染為 HTML。由於 Web API 如 window、localStorage 和 navigator 在伺服器上不可用，您需要確保僅在瀏覽器中執行時才安全地存取這些 API。例如：

'use client';

import { useEffect } from 'react';

export default function ClientComponent() {
  useEffect(() => {
    // 現在您可以存取 `window`
    console.log(window.innerHeight);
  }, [])

  return ...;
}

不支援的功能

需要 Node.js 伺服器或在構建過程中無法計算的動態邏輯的功能不受支援：

• 使用 dynamicParams: true 的動態路由
• 沒有 generateStaticParams() 的動態路由
• 依賴 Request 的路由處理器
• Cookies
• Rewrites
• Redirects
• Headers
• 中介軟體 (Middleware)
• 增量靜態再生 (ISR)
• 使用預設 loader 的圖片優化
• 草稿模式 (Draft Mode)

嘗試在 next dev 中使用這些功能會導致錯誤，類似於在根佈局中將 dynamic 選項設為 error。

export const dynamic = 'error'

部署

使用靜態匯出時，Next.js 可以部署並託管在任何能夠提供 HTML/CSS/JS 靜態資源的網頁伺服器上。

執行 next build 時，Next.js 會將靜態匯出生成到 out 資料夾中。例如，假設您有以下路由：

• /
• /blog/[id]

執行 next build 後，Next.js 將生成以下檔案：

• /out/index.html
• /out/404.html
• /out/blog/post-1.html
• /out/blog/post-2.html

如果您使用像 Nginx 這樣的靜態主機，可以配置從傳入請求到正確檔案的重寫：

server {
  listen 80;
  server_name acme.com;

  root /var/www/out;

  location / {
      try_files $uri $uri.html $uri/ =404;
  }

  # 當 `trailingSlash: false` 時需要此設定
  # 當 `trailingSlash: true` 時可以省略
  location /blog/ {
      rewrite ^/blog/(.*)$ /blog/$1.html break;
  }

  error_page 404 /404.html;
  location = /404.html {
      internal;
  }
}

版本歷史