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

Next.js 允许先以静态网站或单页应用（SPA）起步，之后再按需增加要求服务器的功能。

运行 next build 时，每个路由生成一个 HTML 文件。把严格的 SPA 拆为独立 HTML，能够避免客户端加载不必要的 JavaScript，减小包体并加快页面加载。

静态导出可以部署到任何能提供 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 后，会创建 out 目录，保存应用的 HTML、CSS 与 JS。

支持的功能

Next.js 核心在设计时就考虑了静态导出。

服务端组件

构建静态导出时，app 目录使用的服务端组件会在构建阶段运行，类似传统静态站点生成。

首次访问使用静态 HTML，客户端路由导航使用静态载荷。除非组件调用不支持的动态服务端函数，否则无需修改。

app/page.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 缓存请求。

TypeScript，app/other/page.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
}

JavaScript，app/other/page.js：

'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。例如以下首页路由支持客户端导航。

TypeScript：

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

JavaScript：

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 定义自定义图片 loader，静态导出也能使用 next/image。例如借助 Cloudinary：

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

module.exports = nextConfig

loader 定义从远程来源取得图片的方式。以下构建 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}`
}

my-loader.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 中图片的相对路径。

TypeScript：

import Image from 'next/image'

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

JavaScript：

import Image from 'next/image'

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

路由处理器

Route Handler 在 next build 时生成静态响应，只支持 GET。可根据缓存或未缓存数据生成 HTML、JSON、TXT 等静态文件。

启用静态导出时，需要通过 export const dynamic = 'force-static' 显式标记，确保预渲染。

app/data.json/route.ts：

export const dynamic = 'force-static'

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

app/data.json/route.js：

export const dynamic = 'force-static'

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

构建后生成包含 { name: 'Lee' } 的 data.json 静态文件。如果必须读取传入请求的动态值，就不能使用静态导出。

浏览器 API

客户端组件也会在构建阶段预渲染为 HTML。服务器没有 window、localStorage、navigator 等 Web 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 服务器，或无法在构建阶段计算的动态功能不受支持，包括：

• dynamicParams: true 的动态路由。
• 没有 generateStaticParams() 的动态路由。
• 依赖 Request 的路由处理器。
• Cookies。
• Rewrites。
• Redirects。
• Headers。
• Proxy。
• 增量静态再生成。
• 使用默认 loader 的图片优化。
• Draft Mode。
• Server Actions。
• 拦截路由。

在 next dev 使用这些功能会报错，类似在根布局设置：

export const dynamic = 'error'

部署

可部署到任何静态 Web 服务器。next build 把结果写入 out。

例如路由 / 和 /blog/[id]，构建后生成：

• /out/index.html
• /out/404.html
• /out/blog/post-1.html
• /out/blog/post-2.html

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

部署到 GitHub Pages，可以使用官方模板创建项目，或参考它配置已有项目。

版本历史

版本	变化
v14.0.0	移除 next export，改用 "output": "export"
v13.4.0	稳定版 App Router 增强静态导出，支持 React 服务端组件与路由处理器
v13.3.0	弃用 next export，由 "output": "export" 替代

全部文档的语义概览见站点地图，完整索引见 llms.txt。

---

原文：How to create a static export of your Next.js application。作者／维护方：Next.js 文档维护者 / Vercel。本文为中文翻译，代码及命令保留原文。

原站版权声明：© 2026 Vercel, Inc.