返回

gt-next@6.10.0

Ernest McCarter avatarErnest McCarter
gt-nextv6.10.0缓存组件SSG静态站点生成弃用i18n

概览

gt-next 6.10.0 引入了对缓存组件的实验性支持，同时弃用了来自 gt-next@6.9 的旧版静态请求函数。

  • 新增对缓存组件的实验性支持，可搭配 experimentalLocaleResolution 使用
  • 弃用来自 gt-next@6.9 的旧版静态请求函数

缓存组件

要启用缓存组件功能，请在你的 gt-next 配置中添加 experimentalLocaleResolution: true，并参阅 Next.js Cache Components 指南。在使用包含可翻译内容的缓存组件时，必须将 locale 作为参数传入，以确保在不同 locales 间能够正确使缓存失效。

考虑如下应用结构：

import { Suspense } from "react";
import { getLocale, getLocales } from "gt-next/server";

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

async function CachedContent({locale: _locale}: {locale: string}) {
  "use cache"
  return (
    <div>
      <T><h1>缓存内容</h1></T>
    </div>
  )
}
export default async function Home() {
  const locale = await getLocale()
  return (
    <div>
      <CachedContent locale={locale} />
    </div>
  );
}

对 locale 参数的要求

被缓存的组件会将其参数作为缓存键，任何包含可翻译内容的缓存组件，如果希望在用户的 locale 变更时能更新，必须接收一个 locale 参数。比如，CachedContent 必须接收一个 locale 参数，以便为每个 locale 创建独立的缓存条目。缺少这个参数时，组件将不区分用户的 locale，总是返回相同的缓存内容。

配置说明

当启用 experimentalLocaleResolution 时：

  • 必须启用 I18n Proxy，语言环境解析才能生效（参见 I18n Proxy）
  • 它会覆盖所有自定义的 getLocale 函数（语言环境解析将通过读取 URL 路径来完成）
  • 它会禁用 getRegion 和 getDomain 函数
  • 它与已弃用的 experimentalEnableSSG 配置冲突——同一时间只能启用其中一个
  • 可以使用 experimentalLocaleResolutionParam 自定义语言环境参数的名称（默认为 'locale'）
export default withGTConfig(nextConfig, {
  experimentalLocaleResolution: true,
  // 可选：自定义参数名称
  experimentalLocaleResolutionParam: 'lang',
})

弃用旧版静态请求函数

随着在 gt-next@6.9 中引入对静态渲染的支持，我们现在开始弃用旧版的静态请求函数（getStaticLocale、getStaticRegion、getStaticDomain），转而推荐使用标准请求函数（getLocale、getRegion、getDomain）。

此项弃用与我们在保持完整功能的同时简化 API 接口范围的目标一致。旧版静态函数仍然可以继续使用，但会输出弃用警告信息。我们建议为保持一致性迁移到标准请求函数。

迁移指南

旧版 SSG

替换已弃用的静态请求函数：

// 之前（已废弃）
export default withGTConfig(nextConfig, {
  experimentalEnableSSG: true,
})

// 之后  
export default withGTConfig(nextConfig, {
  // 默认启用
})

移除所有自定义的 getStaticLocale、getStaticRegion 或 getStaticDomain 函数，改为使用自定义的 getLocale、getRegion 或 getDomain 函数。你必须添加一个自定义的 getLocale 函数，并禁用 getRegion 函数。更多信息，请参阅 SSG 指南。

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

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

针对缓存组件

启用实验性 locale 解析功能，并确保缓存组件能够接收 locale 参数：

const nextConfig = {
  cacheComponents: true,
}

// 配置
export default withGTConfig(nextConfig, {
  experimentalLocaleResolution: true,
})
// 组件实现
async function MyCachedComponent({locale}: {locale: string}) {
  "use cache"
  // 在此处添加国际化内容
  return <T>Content for <Var>{locale}</Var></T>
}

// 用法
export default async function Page() {
  const locale = await getLocale()
  return <MyCachedComponent locale={locale} />
}