# General Translation React SDKs (gt-react, gt-next): createNextMiddleware
URL: https://generaltranslation.com/zh/docs/react/nextjs/reference/functions/create-next-middleware.mdx
---

title: createNextMiddleware
description: 使用 General Translation 为 Next.js 应用添加区域设置路由和检测。createNextMiddleware 的 API 参考。

---

`gt-next/middleware` 中的 `createNextMiddleware` 函数可为 Next.js 应用添加基于区域设置的路由和检测功能。它会检测每位访客的区域设置，将其保存到 cookie 中，并将其路由到页面的本地化版本。

请参考 [App Router 中间件指南](/docs/react/nextjs/app-router-middleware) 或 [Pages Router 中间件指南](/docs/react/nextjs/pages-router-middleware) 进行针对特定路由器的设置。

## 概览 [#overview]

创建 `middleware`，并将它与路径匹配器一起从中间件文件中导出。把它放在项目根目录下——Next.js 16+ 使用 `proxy.ts`，Next.js 15 及以下版本使用 `middleware.ts`——不要放在 `app/` 或 `pages/` 中。

```ts title="proxy.ts"
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  // 匹配所有路径，但排除 API 路由、静态文件和 Next.js 内部路径
  matcher: ['/((?!api|static|.*\\..*|_next).*)'],
};
```

## 工作原理 [#how-it-works]

中间件会按以下顺序，从这些来源确定每个请求的区域设置：

1. **URL 区域设置** — URL 路径中的区域设置前缀，例如 `/es/about`。
2. **Cookie** — 访客之前选择的区域设置。
3. **浏览器请求头** — `Accept-Language` 请求头。
4. **默认区域设置** — 你配置的 `defaultLocale`，作为回退值。

随后，它会设置一个区域设置 Cookie；启用 `localeRouting` 时，还会重定向或重写到正确的本地化路径。默认情况下，`defaultLocale` 不带前缀 (`/about` 保持为 `/about`) ，而其他区域设置会带前缀 (`/es/about`) 。启用 General Translation 服务后，区域设置代码会标准化为规范格式，不受支持的区域设置则会产生构建时警告。

## 选项 [#options]

`createNextMiddleware` 接收一个选项对象。所有字段均为可选。

| 选项                                              | 描述                          | 类型        | 可选 | 默认值     |
| ----------------------------------------------- | --------------------------- | --------- | -- | ------- |
| [`localeRouting`](#locale-routing)              | 启用基于区域设置的路由。                | `boolean` | 是  | `true`  |
| [`prefixDefaultLocale`](#prefix-default-locale) | 也为 URL 中的默认区域设置添加前缀。        | `boolean` | 是  | `false` |
| [`ignoreSourceMaps`](#ignore-source-maps)       | 跳过 Next.js 的 source-map 请求。 | `boolean` | 是  | `true`  |
| [`pathConfig`](#path-config)                    | 本地化路径覆盖配置。                  | `object`  | 是  | `{}`    |

*注意：如果要限制中间件在哪些路径名上运行，请在 `withGTConfig` 中设置 [`pathRegex`](/docs/react/nextjs/config#path-regex)——它不是中间件选项。你在导出的 `config` 中配置的 `matcher` 才是 Next.js 用来决定是否运行中间件的依据。*

### `localeRouting` [#locale-routing]

**类型** `boolean` · **可选** · **默认值** `true`

启用基于区域设置的路由和重定向。设为 `false` 时，中间件仍会检测并存储区域设置，但不会添加区域设置前缀，也不会重写路径。

### `prefixDefaultLocale` [#prefix-default-locale]

**类型** `boolean` · **可选** · **默认值** `false`

当为 `false` (默认值) 时，默认区域设置的路径不带前缀 (`/about`) ，而其他区域设置的路径会带前缀 (`/es/about`) 。当为 `true` 时，所有区域设置的路径都会带前缀，包括默认区域设置 (`/en/about`) 。

### `ignoreSourceMaps` [#ignore-source-maps]

**类型** `boolean` · **可选** · **默认值** `true`

当为 `true` 时，针对 Next.js source maps 的请求会直接透传，不做任何处理。

### `pathConfig` [#path-config]

**类型** `object` · **可选** · **默认值** `{}`

将共享路径映射为本地化路径，使同一路由在不同区域设置下可以使用不同的 URL。每个键都是共享路径；每个值既可以是单个本地化路径，也可以是按区域设置分别指定的映射。`[id]` 这类动态片段会被保留。

```ts title="proxy.ts"
export default createNextMiddleware({
  pathConfig: {
    // 英文：/products，中文：/zh/产品
    '/products': {
      zh: '/产品',
    },
    // 动态路由：/product/123，/zh/产品/123
    '/product/[id]': {
      zh: '/产品/[id]',
    },
  },
});
```

## 示例 [#example]

```ts title="proxy.ts"
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware({
  prefixDefaultLocale: true,
  pathConfig: {
    '/about': {
      fr: '/a-propos',
    },
  },
});

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

*警告：请务必仔细测试你的 matcher。范围过宽的 matcher 可能会导致重定向循环，或使静态资源无法正常访问。*