跳到内容
页面路由指南静态导出

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

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',
 
  // 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 资产。

您可以使用 getStaticPropsgetStaticPathspages 目录中的每个页面(或动态路由的更多页面)生成 HTML 文件。

支持的功能

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

图片优化

通过在 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
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 静态资源的 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;
  }
 
  # 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"