跳到主要內容

靜態匯出

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',
 
  // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
  // trailingSlash: true,
 
  // Optional: Prevent automatic `/me` -> `/me/`, instead preserve `href`
  // skipTrailingSlashRedirect: true,
 
  // Optional: Change the output directory `out` -> `dist`
  // distDir: 'dist',
}
 
module.exports = nextConfig

執行 next build 後,Next.js 將建立一個 out 資料夾,其中包含您應用程式的 HTML/CSS/JS 資源。

您可以使用 getStaticPropsgetStaticPaths 為您 pages 目錄中的每個頁面產生一個 HTML 檔案(或更多用於動態路由)。

支援的功能

支援建置靜態網站所需的大多數核心 Next.js 功能,包括

圖片最佳化

透過在 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

my-loader.ts
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 中圖片的相對路徑

app/page.tsx
import Image from 'next/image'
 
export default function Page() {
  return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}

不支援的功能

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

部署

透過靜態匯出,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 這樣的靜態主機,您可以設定從傳入請求到正確檔案的重寫

nginx.conf
server {
  listen 80;
  server_name acme.com;
 
  root /var/www/out;
 
  location / {
      try_files $uri $uri.html $uri/ =404;
  }
 
  # This is necessary when `trailingSlash: false`.
  # You can omit this when `trailingSlash: true`.
  location /blog/ {
      rewrite ^/blog/(.*)$ /blog/$1.html break;
  }
 
  error_page 404 /404.html;
  location = /404.html {
      internal;
  }
}

版本歷史

版本變更
v14.0.0next export 已移除,改用 "output": "export"
v13.4.0App Router (穩定版) 新增了增強的靜態匯出支援,包括使用 React 伺服器元件和路由處理器。
v13.3.0next export 已被棄用,並由 "output": "export" 取代