静态导出

Next.js 支持以静态站点或单页应用程序（SPA）启动，然后稍后可选择升级以使用需要服务器的功能。

当运行next build, Next.js 为每个路由生成一个 HTML 文件。通过将严格的单页应用程序 (SPA) 分解为单独的 HTML 文件，Next.js 可以避免在客户端加载不必要的 JavaScript 代码，从而减少包的大小并加快页面加载速度。

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

配置

要启用静态导出，请在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 资源。

支持的功能

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

服务器组件

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

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

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的客户端组件来缓存请求。

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

"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)。例如，以下索引路由允许您在客户端导航到不同的帖子：

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

import Link from "next/link";

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

图像优化

通过在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}`;
}

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 <img alt="turtles" src="/turtles.jpg" width={300} height={300} />;
}

import Image from "next/image";

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

路由处理程序

在运行next build时，路由处理程序将渲染静态响应。仅 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。

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

浏览器 APIs

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

'use client';

import { useEffect } from 'react';

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

  return ...;
}

不支持的功能

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

Dynamic Routes with dynamicParams: true
Dynamic Routes without generateStaticParams()
Route Handlers that rely on Request
Cookies
Rewrites
Redirects
Headers
Middleware
Incremental Static Regeneration
Image Optimization with the default loader
Draft Mode
Server Actions

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

export const dynamic = "error";

部署

使用静态导出，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 这样的静态主机，您可以配置将传入请求到正确文件的 rewrite：

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

版本历史

Version	Changes
`v14.0.0`	`next export`已被删除，取而代之的是`"output": "export"`
`v13.4.0`	App Router（稳定版）增加了增强的静态导出支持，包括使用 React 服务器组件和路由处理程序。
`v13.3.0`	`next export`已被弃用，取而代之的是 `"output": "export"`

配置​

支持的功能​

服务器组件​

客户端组件​

图像优化​

路由处理程序​

浏览器 APIs​

不支持的功能​

部署​

版本历史​

配置