靜態匯出 (Static Exports)

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

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

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

設定

要啟用靜態匯出，請在 next.config.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 和客戶端路由導航的靜態負載。使用靜態匯出時，除非伺服器元件使用了動態伺服器功能，否則無需對其進行任何更改。

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
}

'use client'

import useSWR from 'swr'

const fetcher = (url) => 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>
    </>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>索引頁面</h1>
      <p>
        <Link href="/other">其他頁面</Link>
      </p>
    </>
  )
}

圖片最佳化 (Image Optimization)

透過 next/image 進行的圖片最佳化可以與靜態匯出一起使用，只需在 next.config.js 中定義自訂圖片載入器。例如，您可以使用 Cloudinary 等服務最佳化圖片：

next.config.js

/** @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}`
}

export default function cloudinaryLoader({ src, width, quality }) {
  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} />
}

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' })
}

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 資料夾中。不再需要 next export。例如，假設您有以下路由：

/
/blog/[id]

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

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

如果您使用 Nginx 等靜態主機，可以設定從傳入請求到正確檔案的重寫規則：

nginx.conf

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;
  }
}

版本歷史

版本	變更
`v13.4.0`	App Router (穩定版) 增加了增強的靜態匯出支援，包括使用 React 伺服器元件和路由處理器。
`v13.3.0`	`next export` 已被棄用，改為使用 `"output": "export"`

On this page