跳到主要内容

📦 plugin-client-redirects

道格龙（Docusaurus）插件，用于生成客户端重定向。

该插件会为你的静态站点额外生成 HTML 页面，通过 JavaScript 将用户重定向到你现有的道格龙页面。

production only

该插件在开发环境下始终处于非激活状态，仅在生产环境下生效，因为它依赖于构建产物。

注意

建议优先使用服务端重定向。

在使用本插件前，请先确认你的托管服务商是否已提供此功能。

安装​

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

配置​

可用配置项：

选项类型默认值说明
fromExtensionsstring[][]重定向后需要移除的路由扩展名。
toExtensionsstring[][]重定向后需要追加到路由的扩展名。
redirectsRedirectRule[][]重定向规则列表。
createRedirectsCreateRedirectsFnundefined用于生成重定向规则的回调函数。道格龙会针对每个已创建的路径调用此回调，并根据返回值生成更多重定向路径。
备注

该插件还会读取 siteConfig.onDuplicateRoutes 配置项，在多个文件输出到同一路径时调整日志级别。

类型定义​

RedirectRule​

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

"from" 和 "to" 是本插件的核心概念。"from" 表示你希望创建的路径（即将额外生成的 HTML 文件）；"to" 表示你希望重定向到的路径，通常是道格龙已知的路由。

因此，同一个 "to" 可以有多个 "from"，我们会为每个 "from" 生成一个重定向到同一目标的 HTML 文件。而一个 "from" 只能有一个 "to"，因为每个 HTML 文件只能有唯一的重定向目标。

CreateRedirectsFn​

// 参数 `path` 是道格龙已创建的路由，可视为 "to"，你的返回值为 "from"。返回假值时不会为该路径创建任何重定向页面。
type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;

配置示例​

以下是一个配置示例：

docusaurus.config.js
export default {
  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 和 /docs/support/X 重定向到 /community/X
            return [
              existingPath.replace('/community', '/docs/team'),
              existingPath.replace('/community', '/docs/support'),
            ];
          }
          return undefined; // 返回假值：不创建重定向
        },
      },
    ],
  ],
};