静态站点生成

概览

Static Site Generation (SSG) 会在构建时预渲染页面，生成静态 HTML files，从而无需 server-side 处理即可直接对外提供。与国际化结合时，SSG 会为每个 locale 生成对应的预渲染版本。

设置

设置要求

要使用 GT 启用 SSG，你需要：

带有 middleware 路由的 App Router - 参见 middleware 指南
自定义 getLocale 函数 - 用于在静态渲染时进行 locale 检测
禁用 getRegion - 静态渲染时不支持区域检测
generateStaticParams 函数 - 用于为每个 locale 生成静态参数

步骤 1：配置中间件

为动态请求配置中间件（参见中间件指南）：

// 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).*)",
  ],
}

步骤 2：定义 locale 和地区检测

创建 getLocale 和 getRegion 函数，用于在静态渲染期间进行 locale 和地区检测：

Next.js 15.5+

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

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

Next.js 15.1-15.4

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

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

步骤 3：禁用 `getRegion`

由于在静态渲染期间不支持区域检测，你需要重写 getRegion 函数，使其始终返回一个固定的区域。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

步骤 4：配置 `generateStaticParams`

确保已为各个 locale 配置好 generateStaticParams。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

其他配置

如果你不希望在项目根目录中放置 getLocale.ts 和 getRegion.ts，可以在 next.config.js 文件中指定一个自定义目录。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

常见问题

Next.js 版本兼容性

在 Next.js 15.1 之前的版本中，在静态生成阶段无法访问 URL 路径参数。若要在 SSG 中使用 gt-next，你需要升级到 Next.js 15.1 或更高版本。

页面未进行静态生成

如果你的页面未被静态生成，请确保：

你的 getLocale 和 getRegion 函数已正确配置

位于 `[locale]` 目录之外的 Layout/Page

如果在 [locale] 目录之外存在 layout.tsx 或 page.tsx 文件，将会阻止静态生成。你很可能会看到以下错误：

在模块 [next]/root-params.js [app-rsc] (ecmascript) 中未找到导出的 locale。
该模块的所有导出都是静态已知的(它没有动态导出)。因此可以静态确定所请求的导出不存在。

所有 layout.tsx 文件都必须位于 [locale] 目录中。如需更多信息，请参阅相关的 Next.js issue。

概览

设置

设置要求

要使用 GT 启用 SSG，你需要：

带有 middleware 路由的 App Router - 参见 middleware 指南
自定义 getLocale 函数 - 用于在静态渲染时进行 locale 检测
禁用 getRegion - 静态渲染时不支持区域检测
generateStaticParams 函数 - 用于为每个 locale 生成静态参数

步骤 1：配置中间件

为动态请求配置中间件（参见中间件指南）：

// 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).*)",
  ],
}

步骤 2：定义 locale 和地区检测

创建 getLocale 和 getRegion 函数，用于在静态渲染期间进行 locale 和地区检测：

Next.js 15.5+

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

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

Next.js 15.1-15.4

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

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

步骤 3：禁用 `getRegion`

由于在静态渲染期间不支持区域检测，你需要重写 getRegion 函数，使其始终返回一个固定的区域。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

步骤 4：配置 `generateStaticParams`

确保已为各个 locale 配置好 generateStaticParams。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

其他配置

如果你不希望在项目根目录中放置 getLocale.ts 和 getRegion.ts，可以在 next.config.js 文件中指定一个自定义目录。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

常见问题

Next.js 版本兼容性

在 Next.js 15.1 之前的版本中，在静态生成阶段无法访问 URL 路径参数。若要在 SSG 中使用 gt-next，你需要升级到 Next.js 15.1 或更高版本。

页面未进行静态生成

如果你的页面未被静态生成，请确保：

你的 getLocale 和 getRegion 函数已正确配置

位于 `[locale]` 目录之外的 Layout/Page

如果在 [locale] 目录之外存在 layout.tsx 或 page.tsx 文件，将会阻止静态生成。你很可能会看到以下错误：

在模块 [next]/root-params.js [app-rsc] (ecmascript) 中未找到导出的 locale。
该模块的所有导出都是静态已知的(它没有动态导出)。因此可以静态确定所请求的导出不存在。

所有 layout.tsx 文件都必须位于 [locale] 目录中。如需更多信息，请参阅相关的 Next.js issue。

概览

设置

设置要求

要使用 GT 启用 SSG，你需要：

带有 middleware 路由的 App Router - 参见 middleware 指南
自定义 getLocale 函数 - 用于在静态渲染时进行 locale 检测
禁用 getRegion - 静态渲染时不支持区域检测
generateStaticParams 函数 - 用于为每个 locale 生成静态参数

步骤 1：配置中间件

为动态请求配置中间件（参见中间件指南）：

// 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).*)",
  ],
}

步骤 2：定义 locale 和地区检测

创建 getLocale 和 getRegion 函数，用于在静态渲染期间进行 locale 和地区检测：

Next.js 15.5+

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

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

Next.js 15.1-15.4

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

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

步骤 3：禁用 `getRegion`

由于在静态渲染期间不支持区域检测，你需要重写 getRegion 函数，使其始终返回一个固定的区域。

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

步骤 4：配置 `generateStaticParams`

确保已为各个 locale 配置好 generateStaticParams。

page.tsx

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

其他配置

如果你不希望在项目根目录中放置 getLocale.ts 和 getRegion.ts，可以在 next.config.js 文件中指定一个自定义目录。

// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: 'src/i18n/getLocale.ts',
  getRegionPath: 'src/i18n/getRegion.ts',
})

常见问题

Next.js 版本兼容性

在 Next.js 15.1 之前的版本中，在静态生成阶段无法访问 URL 路径参数。若要在 SSG 中使用 gt-next，你需要升级到 Next.js 15.1 或更高版本。

页面未进行静态生成

如果你的页面未被静态生成，请确保：

你的 getLocale 和 getRegion 函数已正确配置

位于 `[locale]` 目录之外的 Layout/Page

如果在 [locale] 目录之外存在 layout.tsx 或 page.tsx 文件，将会阻止静态生成。你很可能会看到以下错误：

在模块 [next]/root-params.js [app-rsc] (ecmascript) 中未找到导出的 locale。
该模块的所有导出都是静态已知的(它没有动态导出)。因此可以静态确定所请求的导出不存在。

所有 layout.tsx 文件都必须位于 [locale] 目录中。如需更多信息，请参阅相关的 Next.js issue。

静态站点生成

本页目录

静态站点生成

本页目录

静态站点生成

本页目录

GitHub在 GitHub 上加星标

GitHub在 GitHub 上加星标

在 GitHub 上加星标

在 GitHub 上加星标