概览

静态渲染是 Next.js 框架的核心能力之一，它会在构建时预渲染页面，从而实现最佳性能和 SEO 效果。 在此基础上，任何原生支持 Next.js 的库都应当能够在这种渲染模型下无缝运行。 gt-next 6.9.0 引入了静态渲染支持，使国际化应用可以在不牺牲语言环境检测或翻译功能的前提下，充分利用 Next.js 的完整静态生成能力。

什么是静态渲染？

静态渲染是在构建阶段生成 HTML，而不是在每次请求时生成。 这种方式虽然能带来极佳的性能，但也会给那些通常依赖请求头、Cookie 或中间件来确定用户语言环境的 i18n 库带来挑战。 在静态渲染过程中，这些与请求时机相关的依赖不可用，因此需要借助其他方式进行语言环境检测。

静态渲染设置

在配置 gt-next 之前，请先根据 generateStaticParams 文档 将你的 Next.js 应用配置为使用静态生成。

该设置涉及三个关键组件：

1. 在配置中启用静态渲染

export default withGTConfig(nextConfig, {
  experimentalEnableSSG: true,
})

2. 配置 Middleware

为动态请求配置 Middleware：

// proxy.ts（Next.js 16+）或 middleware.ts（Next.js 15 及以下版本）
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    "/((?!api|static|.*\\..*|_next).*)",
  ],
}

3. 定义静态语言环境检测

创建一个 getStaticLocale 函数，用于在静态渲染阶段确定语言环境。此函数只会在静态生成时运行——在 SSR 期间，将使用默认行为（读取 headers、cookies 等）。

Next.js 15.5+

// getStaticLocale.ts
import { locale } from "next/root-params";

export default async function getStaticLocale() {
  return await locale();
}

Next.js 15.1–15.4

// getStaticLocale.ts  
import { unstable_rootParams } from "next/server";

export default async function getStaticLocale() {
  return (await unstable_rootParams())?.locale;
}

在静态渲染阶段，可以调用 getStaticRegion 来自定义地区检测。

优点

Next.js 原生支持：利用 Next.js 内置的 root 参数系统，实现与静态渲染的兼容。

其他功能

除了静态生成外，此版本还支持自定义 getLocale() 和 getRegion() 函数，可在 SSR 和静态渲染环境中进行配置。