next.js 中文文档

主题

静态导出 ​

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

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

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

配置 ​

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

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 资源。

图像优化 ​

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

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

module.exports = nextConfig

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

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

须知：以上内容为 Next.js 官方文档的翻译，仅供学习和参考，不包含任何额外的文本或解释。

不支持的特性 ​

需要 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
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" 替换