Next.js static export

部署
Next.js 静态网站

把 Next.js app 导出成静态 HTML 和资源文件，上传 out 目录，不需要执行 Node.js 服务器也能全球发布。

查看设置指南
next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
output: 'export',
// Optional for static deployments
images: { unoptimized: true },
}

module.exports = nextConfig
已启用静态导出

Static export 支持矩阵

上传 out 前，先确认 app 符合静态导出模型。

适合

  • 构建时生成的静态路由
  • 可静态渲染的 App Router 页面
  • Pages Router getStaticProps / getStaticPaths
  • Hydration 后的 client-side data fetching
  • next/link、dynamic imports、CSS Modules 和静态资源

需要其他 runtime

  • 需要服务器执行的 API routes 和 route handlers
  • Middleware、rewrites、redirects 和自定义 headers
  • getServerSideProps 与 request-time rendering
  • Incremental Static Regeneration
  • 没有自定义静态策略的默认 next/image optimization

需要框架能力，但不需要服务器时使用 Next.js

保留框架，拿掉服务器

Next.js static export 让你保留文件式路由、layout、metadata、build-time rendering、CSS 支持，以及需要时的 client-side React。

输出结果仍然只是文件。这很适合营销页、文档站、作品集、产品页、内容中心，以及能在构建时准备好的页面。

像静态资源一样快

预先生成的 HTML 可以积极缓存，并直接从边缘节点提供，不必等待服务器即时 render。

运维负担更少

没有 Node runtime，代表生产环境需要维护的环节更少，部署产物也更清楚。

执行边界清楚

需要服务器代码的页面不该硬做成 static export。能提前构建的页面，out 目录就是干净的发布产物。

常见 static export 阻碍

Blocker 01

因 server-only 功能导致构建失败

从导出路由移除 request-time API，把逻辑移到独立后端，或把该部分部署到支持服务器功能的平台。

Blocker 02

图片在开发环境正常，导出后失效

默认 next/image optimizer 需要服务器。请使用 images.unoptimized、自定义 loader，或一般静态图片资源。

Blocker 03

动态路由缺页

在 App Router 用 generateStaticParams，或在 Pages Router 用 getStaticPaths，在构建时生成路由清单。

Blocker 04

Redirects 或 rewrites 没有套用

Next.js redirects 和 rewrites 不属于 static export。请使用静态页结构、client-side navigation，或可用的平台层 redirect。

Next.js 静态导出检查表

01

设置 output: 'export'

让 Next.js 在构建时输出静态 HTML，而不是期待 next start 或 Node runtime。

output: 'export'
02

构建并检查 /out

执行正式 build，确认 out 目录包含要发布的页面、资源、404 页和静态文件。

npm run build
03

上传并测试路由

上传 out 目录后，检查深层路径、静态资源和未优化图片是否在上线网站正常。

Next.js 部署常见问题

为什么 Next.js Image 组件导出后会坏掉？

默认 Image 优化流程需要服务器。静态导出时，请在 next.config.js 设置 images.unoptimized 为 true。

API routes 或 getServerSideProps 可以在这里用吗？

不行。Static export 会移除 API routes、middleware、getServerSideProps 等服务端 runtime 功能。请把这些逻辑移到独立后端或 serverless 服务。

可以使用 App Router 吗？

可以，只要该路由可静态渲染，且不依赖 headers、cookies 等 dynamic server-only API。

动态内容该怎么处理？

能在构建时取得就先构建；否则在页面 hydration 后由 client-side 加载。Static export 最适合 HTML 可提前准备的页面。

应该上传 .next 还是 out？

output: 'export' 要上传 out。.next 是 Next.js 的内部构建目录，不是你要发布的静态导出产物。

这能取代 Vercel 的 Next.js hosting 吗？

它适合静态导出，不适合每一种 Next.js app。如果你依赖 SSR、middleware、ISR、server actions 或 API routes，就需要支持这些功能的 runtime。