静态站点生成
在构建时预渲染国际化页面,以实现最佳性能
概览
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。
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。
延伸阅读
- 查看用于 locale 路由的 middleware 指南
- 查看 发布说明,了解如何从旧版 SSG 模式迁移
本指南如何?