📦 plugin-client-redirects

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

¥Docusaurus Plugin to generate client-side redirects.

该插件将向你的静态站点写入额外的 HTML 页面，使用 JavaScript 将用户重定向到你现有的 Docusaurus 页面。

¥This plugin will write additional HTML pages to your static site that redirect the user to your existing Docusaurus pages with JavaScript.

仅限生产

该插件在开发中始终处于非活动状态，仅在生产中处于活动状态，因为它适用于构建输出。

¥This plugin is always inactive in development and only active in production because it works on the build output.

警告

最好尽可能使用服务器端重定向。

¥It is better to use server-side redirects whenever possible.

在使用此插件之前，你应该检查你的托管提供商是否不提供此功能。

¥Before using this plugin, you should look if your hosting provider doesn't offer this feature.

安装

¥Installation

npm

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

Yarn

yarn add @docusaurus/plugin-client-redirects

pnpm

pnpm add @docusaurus/plugin-client-redirects

配置

¥Configuration

接受的字段：

¥Accepted fields:

选项	类型	默认	描述
fromExtensions	string[]	[]	重定向后要从路由中删除的扩展。
toExtensions	string[]	[]	重定向后要附加到路由的扩展名。
redirects	RedirectRule[]	[]	重定向规则列表。
createRedirects	CreateRedirectsFn	undefined	用于创建重定向规则的回调。Docusaurus 针对它创建的每个路径查询此回调，并使用其返回值输出更多路径。

注意

当多个文件被发送到同一位置时，该插件还将读取 siteConfig.onDuplicateRoutes 配置来调整其日志记录级别。

¥This plugin will also read the siteConfig.onDuplicateRoutes config to adjust its logging level when multiple files will be emitted to the same location.

类型

¥Types

RedirectRule

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

注意

"from" 和 "to" 的想法是这个插件的核心。"从" 表示你要创建的路径，即要写入的额外 HTML 文件；"to" 表示要重定向到的路径，通常是 Docusaurus 已经知道的路由。

¥The idea of "from" and "to" is central in this plugin. "From" means a path that you want to create, i.e. an extra HTML file that will be written; "to" means a path to want to redirect to, usually a route that Docusaurus already knows about.

这就是为什么同一个 "to" 可以有多个 "from"：我们将创建多个 HTML 文件，它们都重定向到同一目标。另一方面，一个 "from" 永远不能有多个 "to"：编写的 HTML 文件需要有一个确定的目的地。

¥This is why you can have multiple "from" for the same "to": we will create multiple HTML files that all redirect to the same destination. On the other hand, one "from" can never have more than one "to": the written HTML file needs to have a determinate destination.

CreateRedirectsFn

// The parameter `path` is a route that Docusaurus has already created. It can
// be seen as the "to", and your return value is the "from". Returning a falsy
// value will not create any redirect pages for this particular path.
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

配置示例

¥Example configuration

这是一个配置示例：

¥Here's an example configuration:

docusaurus.config.js

export default {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
        toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists)
        redirects: [
          // /docs/oldDoc -> /docs/newDoc
          {
            to: '/docs/newDoc',
            from: '/docs/oldDoc',
          },
          // Redirect from multiple old paths to the new path
          {
            to: '/docs/newDoc2',
            from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
          },
        ],
        createRedirects(existingPath) {
          if (existingPath.includes('/community')) {
            // Redirect from /docs/team/X to /community/X and /docs/support/X to /community/X
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // Return a falsy value: no redirect created
        },
      },
    ],
  ],
};