Next.js 静态导出部署到 GitHub Pages 实践指南.

核心约束

GitHub Pages 只提供静态文件服务。它无法运行 Node.js 服务器。这意味着：没有 SSR、没有 ISR、没有中间件、没有 Route Handler。

Next.js 通过 output: "export" 支持这种部署模式：

// next.config.ts
const nextConfig: NextConfig = {
  output: "export",
  images: {
    unoptimized: true,
  },
};

失去的能力

1. 需要服务器的 Server Component —— cookies()、headers()、searchParams（params 不受影响，构建时已知）。
2. Route Handler —— 不支持 route.ts 文件。API 逻辑需要迁到外部服务或 GitHub Actions。
3. next/image 优化 —— 必须设置 unoptimized: true。可以用 sharp 在构建脚本中预处理图片，或使用 CDN。
4. 动态路由 —— 每个 [slug] 路由都必须提供 generateStaticParams()。

保留的能力

• App Router 的 layouts、loading、error boundaries
• generateStaticParams 用于动态路由
• generateMetadata 用于每页 SEO
• Server Component（构建时渲染）
• Client Component（正常水合）
• Tailwind、PostCSS，所有 CSS 方案

MDX 支持

@next/mdx 包直接集成：

import createMDX from "@next/mdx";
 
const withMDX = createMDX({
  extension: /\.mdx?$/,
});
 
export default withMDX({
  pageExtensions: ["ts", "tsx", "mdx"],
  output: "export",
  images: { unoptimized: true },
});

部署

一个 GitHub Actions 工作流完成构建并将输出推送到 gh-pages 分支：

- uses: peaceiris/actions-gh-pages@v4
  with:
    publish_dir: ./out
    publish_branch: gh-pages

就是这样。推送到 master 分支，站点自动更新。