📦 plugin-client-redirects

用于生成客户端重定向的 Docusaurus 插件。

这个插件会在你的静态网站中写入额外的 HTML 页面，通过 JavaScript 将用户重定向到已有的 Docusaurus 页面。

仅生产环境

这个插件在开发过程中始终不工作，只在生产环境中启用，因为它会在构建输出上工作。

注意

如果可行，你最好用服务端重定向。

在用这个插件前，你应该确定你的托管商是否确实不提供此功能。

安装流程

npm

npm install --save @docusaurus/plugin-client-redirects

Yarn

yarn add @docusaurus/plugin-client-redirects

配置

接受的字段：

选项	类型	默认值	描述
fromExtensions	string[]	[]	重定向后从路径中去除的扩展名。
toExtensions	string[]	[]	重定向后添加到路径中的扩展名。
redirects	RedirectRule[]	[]	重定向规则列表。
createRedirects	CreateRedirectsFn	undefined	用于创建重定向规则的回调。 Docusaurus 会用每一个它创建的路径来调用这个回调，然后用它的返回值来输出更多路径。

备注

插件也会读取 siteConfig.onDuplicateRoutes 配置，在有多个文件被输出到同一路径时调整日志等级。

类型

RedirectRule

type RedirectRule = {
  to: string;
  from: string | string[];
};

备注

"From" 和 "to" 的概念是这个插件的核心。 "From" 指你想要创建的路径，也就是会被写入的额外 HTML 文件；"to" 指你想要重定向到的路径，一般是 Docusaurus 已经知道的路径。

这就是为什么你可以对于同一个 "to" 有多个 "from"：我们会创建多个 HTML 文件，它们全部重定向到同一个目标。 另一方面，一个 "from" 永远不会有多于一个 "to"：写入的 HTML 文件必须有唯一确定的目标。

CreateRedirectsFn

// 参数 `path` 是一个 Docusaurus 已经创建的路径。 它可以
// 被看作是 "to"，而你的返回值就是 "from"。 返回 falsy 的
// 值，就不会为当前路径创建任何重定向页面。
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

示例配置

这是一个示例配置：

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
        toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip （如果后者存在的话）
        redirects: [
          // /docs/oldDoc -> /docs/newDoc
          {
            to: '/docs/newDoc',
            from: '/docs/oldDoc',
          },
          // 将多个旧路径重定向到新路径
          {
            to: '/docs/newDoc2',
            from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
          },
        ],
        createRedirects(existingPath) {
          if (existingPath.includes('/community')) {
            // 将 /docs/team/X 重定向到 /community/X，/docs/support/X 重定向到 /community/X
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // 返回 falsy 值，不创建重定向
        },
      },
    ],
  ],
};