如何创建您的 Next.js 应用的静态导出

Next.js 允许您以静态站点或单页应用（SPA）的形式开始，然后可以选择升级以使用需要服务器的功能。

当运行 next build 时，Next.js 会为每个路由生成一个 HTML 文件。通过将严格的 SPA 拆分为独立的 HTML 文件，Next.js 可以避免在客户端加载不必要的 JavaScript 代码，从而减小打包大小并实现更快的页面加载。

由于 Next.js 支持此静态导出，因此它可以部署并托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。

配置

要启用静态导出，请在 next.config.js 中更改输出模式：

javascript

/**
 * @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 资源。

Pages Router Only

您可以利用 getStaticProps 和 getStaticPaths 为您的 pages 目录中的每个页面生成一个 HTML 文件（或为动态路由生成更多文件）。

App Router Only

支持的功能

Next.js 的核心设计旨在支持静态导出。

服务器组件

当您运行 next build 生成静态导出时，app 目录中使用的服务器组件将在构建期间运行，类似于传统的静态站点生成。

生成的组件将渲染为静态 HTML 用于初始页面加载，并生成一个静态负载用于客户端路由间的导航。使用静态导出时，您的服务器组件无需进行任何更改，除非它们使用了动态服务器函数。

tsx

export default async function Page() {
  // This fetch will run on the server during `next build`
  const res = await fetch('https://api.example.com/...')
  const data = await res.json()

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

客户端组件

如果您想在客户端执行数据获取，您可以使用客户端组件配合 SWR 来记忆请求。

tsx

'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 'Failed to load'
  if (!data) return 'Loading...'

  return data.title
}

jsx

'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 'Failed to load'
  if (!data) return 'Loading...'

  return data.title
}

由于路由转换发生在客户端，这就像一个传统的 SPA。例如，以下索引路由允许您在客户端导航到不同的文章：

tsx

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>Index Page</h1>
      <hr />
      <ul>
        <li>
          <Link href="/post/1">Post 1</Link>
        </li>
        <li>
          <Link href="/post/2">Post 2</Link>
        </li>
      </ul>
    </>
  )
}

jsx

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>Index Page</h1>
      <p>
        <Link href="/other">Other Page</Link>
      </p>
    </>
  )
}

Pages Router Only

支持的功能

大多数构建静态站点所需的核心 Next.js 功能都受支持，包括：

使用 getStaticPaths 时的动态路由
next/link 的预加载
预加载 JavaScript
动态导入
任何样式选项（例如 CSS 模块、styled-jsx）
客户端数据获取
getStaticProps
getStaticPaths

图像优化

通过 next/image 进行的图像优化可以通过在 next.config.js 中定义自定义图像加载器来与静态导出一起使用。例如，您可以使用 Cloudinary 等服务优化图像：

javascript

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

module.exports = nextConfig

此自定义加载器将定义如何从远程源获取图像。例如，以下加载器将为 Cloudinary 构建 URL：

typescript

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

javascript

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 中图像的相对路径：

tsx

import Image from 'next/image'

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

jsx

import Image from 'next/image'

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

App Router Only

路由处理程序

路由处理程序在运行 next build 时将渲染静态响应。仅支持 GET HTTP 动词。这可用于从缓存或未缓存的数据生成静态 HTML、JSON、TXT 或其他文件。例如：

typescript

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

javascript

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

上述文件 app/data.json/route.ts 将在 next build 期间渲染为静态文件，生成包含 { name: 'Lee' } 的 data.json。

如果您需要从传入请求中读取动态值，则无法使用静态导出。

浏览器 API

客户端组件在 next build 期间会预渲染为 HTML。由于 window、localStorage 和 navigator 等 Web API 在服务器上不可用，您需要在浏览器中运行时才能安全地访问这些 API。例如：

jsx

'use client';

import { useEffect } from 'react';

export default function ClientComponent() {
  useEffect(() => {
    // You now have access to `window`
    console.log(window.innerHeight);
  }, [])

  return ...;
}

不支持的功能

需要 Node.js 服务器或无法在构建过程中计算的动态逻辑功能不受支持：

App Router Only

尝试在 next dev 中使用这些功能中的任何一个都将导致错误，类似于在根布局中将 dynamic 选项设置为 error。

jsx

export const dynamic = 'error'

Pages Router Only

部署

借助静态导出，Next.js 可以部署并托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。

当运行 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

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.0`	`next export` 已被移除，取而代之的是 `"output": "export"`
`v13.4.0`	App Router（稳定版）增加了增强的静态导出支持，包括使用 React 服务器组件和路由处理程序。
`v13.3.0`	`next export` 已被弃用，并由 `"output": "export"` 取代

Next.js 允许您以静态站点或单页应用（SPA）的形式开始，然后可以选择升级以使用需要服务器的功能。

由于 Next.js 支持此静态导出，因此它可以部署并托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。

配置

要启用静态导出，请在 next.config.js 中更改输出模式：

javascript

/**
 * @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 资源。

Pages Router Only

您可以利用 getStaticProps 和 getStaticPaths 为您的 pages 目录中的每个页面生成一个 HTML 文件（或为动态路由生成更多文件）。

App Router Only

支持的功能

Next.js 的核心设计旨在支持静态导出。

服务器组件

当您运行 next build 生成静态导出时，app 目录中使用的服务器组件将在构建期间运行，类似于传统的静态站点生成。

tsx

export default async function Page() {
  // This fetch will run on the server during `next build`
  const res = await fetch('https://api.example.com/...')
  const data = await res.json()

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

客户端组件

如果您想在客户端执行数据获取，您可以使用客户端组件配合 SWR 来记忆请求。

tsx

'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 'Failed to load'
  if (!data) return 'Loading...'

  return data.title
}

jsx

'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 'Failed to load'
  if (!data) return 'Loading...'

  return data.title
}

由于路由转换发生在客户端，这就像一个传统的 SPA。例如，以下索引路由允许您在客户端导航到不同的文章：

tsx

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>Index Page</h1>
      <hr />
      <ul>
        <li>
          <Link href="/post/1">Post 1</Link>
        </li>
        <li>
          <Link href="/post/2">Post 2</Link>
        </li>
      </ul>
    </>
  )
}

jsx

import Link from 'next/link'

export default function Page() {
  return (
    <>
      <h1>Index Page</h1>
      <p>
        <Link href="/other">Other Page</Link>
      </p>
    </>
  )
}

Pages Router Only

支持的功能

大多数构建静态站点所需的核心 Next.js 功能都受支持，包括：

使用 getStaticPaths 时的动态路由
next/link 的预加载
预加载 JavaScript
动态导入
任何样式选项（例如 CSS 模块、styled-jsx）
客户端数据获取
getStaticProps
getStaticPaths

图像优化

通过 next/image 进行的图像优化可以通过在 next.config.js 中定义自定义图像加载器来与静态导出一起使用。例如，您可以使用 Cloudinary 等服务优化图像：

javascript

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

module.exports = nextConfig

此自定义加载器将定义如何从远程源获取图像。例如，以下加载器将为 Cloudinary 构建 URL：

typescript

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

javascript

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 中图像的相对路径：

tsx

import Image from 'next/image'

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

jsx

import Image from 'next/image'

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

App Router Only

路由处理程序

路由处理程序在运行 next build 时将渲染静态响应。仅支持 GET HTTP 动词。这可用于从缓存或未缓存的数据生成静态 HTML、JSON、TXT 或其他文件。例如：

typescript

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

javascript

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

上述文件 app/data.json/route.ts 将在 next build 期间渲染为静态文件，生成包含 { name: 'Lee' } 的 data.json。

如果您需要从传入请求中读取动态值，则无法使用静态导出。

浏览器 API

jsx

'use client';

import { useEffect } from 'react';

export default function ClientComponent() {
  useEffect(() => {
    // You now have access to `window`
    console.log(window.innerHeight);
  }, [])

  return ...;
}

不支持的功能

需要 Node.js 服务器或无法在构建过程中计算的动态逻辑功能不受支持：

App Router Only

尝试在 next dev 中使用这些功能中的任何一个都将导致错误，类似于在根布局中将 dynamic 选项设置为 error。

jsx

export const dynamic = 'error'

Pages Router Only

部署

借助静态导出，Next.js 可以部署并托管在任何能够提供 HTML/CSS/JS 静态资源的 Web 服务器上。

当运行 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

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.0`	`next export` 已被移除，取而代之的是 `"output": "export"`
`v13.4.0`	App Router（稳定版）增加了增强的静态导出支持，包括使用 React 服务器组件和路由处理程序。
`v13.3.0`	`next export` 已被弃用，并由 `"output": "export"` 取代

文档导航

配置

支持的功能

服务器组件

客户端组件

支持的功能

图像优化

路由处理程序

浏览器 API

不支持的功能

部署

版本历史

配置

支持的功能

服务器组件

客户端组件

支持的功能

图像优化

路由处理程序

浏览器 API

不支持的功能

部署

版本历史