作者:
    Creation:2026-06-25Last update:2026-06-25

    intlayerProxy

    intlayerProxy 是一个 Vite 插件，它为所有环境注册语言路由中间件：开发服务器（dev server）、预览服务器（preview server）和生产环境 SSR（Nitro / TanStack Start）。

    自 Intlayer v9 起，intlayerProxy 会自动包含在主 intlayer() 插件中，并通过 routing.enableProxy: true 默认启用。仅当您需要更底层的控制或在标准 intlayer() 设置之外使用它时，才需要单独注册它。

    用法

    作为 intlayer() 的一部分（推荐，v9+）

    将 proxy 选项传递给主插件，而不是单独注册 intlayerProxy：

    ts
    // vite.config.tsimport { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [    intlayer({      proxy: {        ignore: (req) => req.url?.startsWith("/api"),      },    }),  ],});

    独立使用（需要时）

    ts
    // vite.config.tsimport { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});

    选项

    ts
    import type { IntlayerProxyPluginOptions } from "vite-intlayer";

    所有选项都是可选的，并作为单个对象传递：

    选项 类型 描述
    ignore (req: IncomingMessage) => boolean 排除语言路由请求的断言函数。返回 true 以跳过请求（例如 API 路由、健康检查）。
    configOptions GetConfigurationOptions 转发给 getConfiguration() 的 Intlayer 配置覆盖项。当您需要代理读取特定的配置文件或覆盖值时使用。

    示例

    ts
    intlayerProxy({  ignore: (req) => req.url?.startsWith("/api"),  configOptions: { configFile: "./config/intlayer.config.ts" },});

    createIntlayerProxyHandler

    createIntlayerProxyHandler 创建一个独立于框架的 Node.js (req, res, next) 中间件，其中包含所有语言路由逻辑。它适用于 Vite 插件 API 不可用的环境（例如普通的 Node.js 服务器或自定义 Nitro 模块）。

    ts
    import { createIntlayerProxyHandler } from "vite-intlayer";const handler = createIntlayerProxyHandler({  ignore: (req) => req.url?.startsWith("/api"),  configOptions: { configFile: "./config/intlayer.config.ts" },});// Express / Connectapp.use(handler);

    生产环境 SSR（通过 h3 的 TanStack Start / Nitro）

    ts
    // server/middleware/intlayerProxy.tsimport { fromNodeMiddleware } from "h3";import { createIntlayerProxyHandler } from "vite-intlayer";export default fromNodeMiddleware(  createIntlayerProxyHandler({    ignore: (req) => req.url?.startsWith("/api"),  }));

    路由行为

    该中间件映射了 next-intlayer 中间件的路由逻辑，并支持所有 Intlayer 路由模式。

    路由模式

    模式 URL 在浏览器中可见 行为
    prefix /zh/about 默认。URL 中的语言前缀。默认语言会重定向到无前缀 URL，除非启用了 prefix-all。
    prefix-all /en/about, /zh/about 所有语言 — 包括默认语言 — 始终带有前缀。
    no-prefix /about URL 中没有语言。语言仅存储在 cookie 中；URL 重写发生在内部。
    search-params /about?locale=zh 语言作为查询参数传递。在缺失或过期时重定向以添加/更新 locale 参数。

    检测优先级

    1. URL 路径前缀（例如 /zh/about → zh）。
    2. Cookie / localStorage 值（intlayer-locale）。
    3. Accept-Language 请求头。
    4. 配置中的 defaultLocale。

    自动绕过

    中间件始终直接传递这些请求，而不进行语言处理：

    • 匹配 ignore 断言的请求。
    • /node_modules/**
    • /@** – Vite 内部（@vite/, @fs/, @id/ 等）。
    • /_** – 服务器内部（__vite_ping, __manifest 等）。
    • 路径以文件扩展名结尾的请求（静态资源）。如果静态资源路径上存在语言前缀（例如 /zh/logo.png），则会将其剥离，以便可以正确提供文件。

    域名路由

    当在您的 Intlayer 配置中配置了 routing.domains 时，中间件处理跨域语言路由：

    • 当 domains.zh = "intlayer.zh" 时，在 intlayer.org 上对 /zh/about 的请求被重定向到 https://intlayer.zh/about。
    • 对 intlayer.zh/about 的请求在内部重写为 /zh/about，以便填充 [locale] 路由参数。

    重定向死循环保护

    中间件在 2 秒滑动窗口内跟踪每个 originalUrl → newUrl 对的重定向计数。该窗口内超过 10 次重定向将返回具有描述性错误的 500 响应，而不是无限循环。

    Nitro / 生产环境 SSR（自动注入，v9+）

    当 intlayerProxy 用作 Vite 插件时，它携带一个 .nitro 属性。nitro/vite 构建插件读取此属性并将其推入 nitroConfig.modules 中，因此 intlayerNitroHandler 会自动注册为 Nitro 服务器中间件 — 生产环境 SSR 不需要手动配置。

    Nitro 处理器使用 h3 v2 的 Web Fetch API 事件模型（而不是 fromNodeMiddleware），因此它与所有 Nitro 预设兼容：Node, Bun, Deno, edge 运行时。

    弃用的别名

    弃用的导出 替代品
    intlayerMiddleware intlayerProxy
    intLayerMiddlewarePlugin intlayerProxy
    为什么Intlayer？