Menu

How to create an static export of your Next.js application

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

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

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

配置

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

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

支持的功能

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

Image Optimization

通过在 next.config.js 中定义自定义图像加载器，可以在静态导出中使用通过 next/image 进行的图像优化。例如，你可以使用 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
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}`
}

然后你可以在应用程序中使用 next/image，定义 Cloudinary 中图像的相对路径：

app/page.tsx
TypeScript
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 静态资源的 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.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;
  }
}

版本历史

版本变更
v14.0.0next export 已被移除，改用 "output": "export"
v13.4.0App Router（稳定版）添加了增强的静态导出支持，包括使用 React Server Components 和 Route Handlers。
v13.3.0next export 已弃用并替换为 "output": "export"