# General Translation React SDKs (gt-react, gt-next, gt-react-native): App Router 静态站点生成
URL: https://generaltranslation.com/zh/docs/react/nextjs/app-router-static-site-generation.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何使用 General Translation 预渲染已本地化的 Next.js App Router 页面。

使用 `generateStaticParams` 为每个区域设置预渲染一个 App Router 路由。区域设置路由和请求区域设置解析的 setup 与动态路由相同。

## 保持你的 Next.js 配置不变 [#config]

静态生成不会改变你的 `withGTConfig` 配置方式：

```ts title="next.config.ts"
import type { NextConfig } from 'next';
import { withGTConfig } from 'gt-next/config';

const nextConfig: NextConfig = {};

export default withGTConfig(nextConfig);
```

## 配置区域设置路由 [#routing]

按照 [App Router middleware 指南](/docs/react/nextjs/app-router-middleware) 创建 `proxy.ts`，将路由移至 `app/[locale]` 下，并定义自定义 [`getLocale`](/docs/react/nextjs/reference/functions/get-locale) 函数。

## 禁用地区检测 [#region]

默认的地区解析器会读取 cookie，这会导致路由变为动态路由。要在预渲染期间禁用地区检测，请在项目根目录添加 `getRegion.ts`：

```ts title="./getRegion.ts"
export default async function getRegion() {
  return undefined;
}
```

`withGTConfig` 会自动识别该文件。

## 生成区域设置路由 [#generate-routes]

为每个已配置的区域设置返回一个路由参数：

```tsx title="app/[locale]/page.tsx"
import { getLocales, T } from 'gt-next';

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

export default function HomePage() {
  return <T>Welcome to our site</T>;
}
```

现在，Next.js 会为每个区域设置分别预渲染一次 `app/[locale]/page.tsx`。

<Callout type="warn">
  此配置可在部署 Next.js 服务器端的同时预渲染页面。存在 `proxy.ts` 或 `middleware.ts` 时，设置了 `output: 'export'` 的项目无法构建。若要实现完全静态导出，请移除middleware，导出 `dynamicParams = false`，生成所有区域设置路径，并直接链接到这些路径；区域设置检测和重定向将不可用。
</Callout>

## 检查 Next.js 兼容性 [#compatibility]

自定义 `getLocale.ts` 文件需要在预渲染期间访问根级 `[locale]` 参数。请使用当前 Next.js 版本提供的 API：

| Next.js 版本           | 根区域设置 API                                |
| -------------------- | ---------------------------------------- |
| 15.5 及更高版本           | `next/root-params` 中的 `locale()`         |
| 15.2.0 和 15.2.3–15.4 | `next/server` 中的 `unstable_rootParams()` |
| 早于 15.2              | 使用此 App Router SSG 配置前请先升级               |

`gt-next` 支持的 peer 依赖版本范围不包括 Next.js 15.2.1 和 15.2.2。请将这些版本升级至 15.2.3 或更高版本。

对于 Next.js 15.2.0 或 15.2.3–15.4，请使用：

```ts title="./getLocale.ts"
import { unstable_rootParams } from 'next/server';

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

对于当前项目，请继续使用 [middleware 指南](/docs/react/nextjs/app-router-middleware#root-locale)中适用于 Next.js 15.5 及更高版本的 `next/root-params` 示例。

## 从构建失败中恢复 [#build-failures]

### 无法确定区域设置

Next.js 预渲染页面时不会运行middleware。请确认项目根目录中存在 `getLocale.ts`，或确认 [`getLocalePath`](/docs/react/nextjs/config#request-function-paths) 指向该文件。

如果任意路由值应返回 404，而不是回退到默认区域设置，请使用 [`isLocaleSupported`](/docs/react/nextjs/reference/functions/is-locale-supported) 验证 `[locale]` 参数。

### `DYNAMIC_SERVER_USAGE`

此错误表示静态渲染期间调用了动态请求 API。请检查：

* `getLocale.ts` 只读取 root 路由参数。
* `getRegion.ts` 返回固定值或 `undefined`。
* 两个函数都未调用 `headers()` 或 `cookies()`。

如果启用了缓存组件，还需遵循更严格的[缓存组件设置](/docs/react/nextjs/cache-components)。

### 根参数导出错误

如果出现提示 `locale` 导出不存在的错误，通常说明项目使用的 API 与其 Next.js 版本不匹配。请参阅[兼容性表](#compatibility)。

`[locale]` 段还必须是 App Router 树中的第一个动态段。请将根布局放在 `app/[locale]/layout.tsx`；位于该段之前的布局无法在预渲染期间读取根区域设置。

### 元数据图片路由

Open Graph、Twitter、图标和 Apple 图标文件在内部是路由处理程序，无法读取 `next/root-params`。请读取 `params.locale`，并在调用其他服务器端辅助函数之前调用 [`registerLocale`](/docs/react/nextjs/reference/functions/register-locale)。请参阅[注册请求区域设置](/docs/react/nextjs/registering-request-locales#metadata-images)。

## Next steps

- /docs/react/nextjs/app-router-middleware
- /docs/react/nextjs/registering-request-locales
- /docs/react/nextjs/cache-components
- /docs/react/nextjs/locale-alias-seo

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.