Next.js 静态导出功能全面解析：从配置到部署指南

概述

Next.js 作为现代 React 框架，提供了强大的静态导出(Static Export)功能，允许开发者将应用构建为纯静态网站或单页应用(SPA)。这种能力为开发者提供了极大的灵活性，既能享受静态网站的高性能优势，又能在需要时无缝升级到需要服务器端功能的完整应用。

静态导出的核心优势

1. 性能优化：Next.js 为每个路由生成独立的 HTML 文件，避免了传统 SPA 加载大量 JavaScript 的问题
2. 渐进增强：可以从纯静态网站开始，后续逐步添加需要服务器端的功能
3. 广泛兼容：生成的静态文件可以部署在任何支持 HTML/CSS/JS 的 Web 服务器上

配置静态导出

启用静态导出只需在项目配置文件中进行简单设置：

// next.config.js
const nextConfig = {
  output: 'export',  // 关键配置项
  
  // 可选配置项
  trailingSlash: true,  // 控制URL末尾斜杠行为
  distDir: 'dist'      // 自定义输出目录
}

module.exports = nextConfig

配置完成后，运行构建命令 next build 会在项目根目录下生成 out 文件夹（或自定义目录），包含所有静态资源。

支持的功能特性

1. 服务端组件处理

在构建过程中，服务端组件会被预渲染为静态HTML：

// app/page.tsx
export default async function Page() {
  // 构建时执行的fetch请求
  const res = await fetch('https://api.example.com/data')
  const data = await res.json()

  return <main>{/* 渲染内容 */}</main>
}

2. 客户端数据获取

对于需要在客户端获取的数据，可以使用SWR等库：

'use client'
import useSWR from 'swr'

export default function Page() {
  const { data } = useSWR('/api/data', fetcher)
  return <div>{data?.title}</div>
}

3. 图片优化

通过自定义加载器实现静态导出中的图片优化：

// next.config.js
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './image-loader.js'
  }
}

// image-loader.js
export default function cloudinaryLoader({ src, width }) {
  return `https://res.cloudinary.com/demo/image/upload/w_${width}${src}`
}

4. 路由处理器

静态导出支持生成静态API响应：

// app/api/data/route.ts
export async function GET() {
  return Response.json({ status: 'success' })
}

不支持的服务器功能

静态导出模式下，以下需要服务器运行时的功能不可用：

1. 动态路由参数（未预先生成的情况）
2. 依赖请求对象的API路由
3. 实时重写、重定向和头信息设置
4. 中间件功能
5. 增量静态再生(ISR)
6. 默认的图片优化加载器
7. 草稿模式
8. 服务器操作

部署策略

构建生成的静态文件可以部署到任何Web服务器。以下是Nginx配置示例：

server {
  listen 80;
  root /var/www/out;

  location / {
    try_files $uri $uri.html $uri/ =404;
  }

  # 处理无后缀的博客路由
  location /blog/ {
    rewrite ^/blog/(.*)$ /blog/$1.html break;
  }

  error_page 404 /404.html;
}

最佳实践建议

1. 路由设计：合理规划路由结构，避免过于复杂的动态路由
2. 数据获取：区分构建时数据和客户端数据，合理使用缓存策略
3. 性能优化：利用静态导出的优势，对不常变的内容进行预渲染
4. 渐进增强：从静态开始，逐步添加动态功能
5. 测试验证：部署前充分测试各路由的静态生成情况

版本演进

• v14.0.0: 移除了 next export 命令，完全转向 output: 'export' 配置
• v13.4.0: 应用路由器(App Router)增强了对静态导出的支持
• v13.3.0: 开始推荐使用 output: 'export' 替代 next export

通过合理利用Next.js的静态导出功能，开发者可以构建高性能、易部署的现代Web应用，同时保留未来扩展的灵活性。