redirect

此插件提供页面与整站重定向功能。

使用方法

npm i -D @vuepress/plugin-redirect@next

.vuepress/config.ts
import { redirectPlugin } from '@vuepress/plugin-redirect'

export default {
  plugins: [
    redirectPlugin({
      // 配置项
    }),
  ],
}

指南

设置重定向

如果你改动了已有页面的地址，你可以在 Frontmatter 中使用 redirectFrom 选项设置重定向到此页面的地址，这样可以保证用户在访问旧链接时重定向到新的地址。

如果你需要将已有的页面重定向到新的页面，可以在 Frontmatter 中使用 redirectTo 选项设置需要重定向到的地址。这样该页面会在访问时重定向到新的地址。

你还可以通过插件选项中的 config 设置一个重定向映射：

当 base 为 /base/ 时：

将 /base/foo.html 重定向到 /base/bar.html
将 /base/baz.html 重定向到 https://example.com/qux.html。

redirect({
  config: {
    '/foo.html': '/bar.html',
    '/baz.html': 'https://example.com/qux.html',
  },
})

将 post 文件夹的路径重定向到 posts 文件夹：

redirect({
  hostname: 'https://example.com',
  config: (app) =>
    Object.fromEntries(
      app.pages
        .filter(({ path }) => path.startsWith('/posts/'))
        .map(({ path }) => [path.replace(/^\/posts\//, '/post/'), path]),
    ),
})

自动多语言

插件可以根据用户的语言首选项，自动将无多语言链接重定向到用户需要的多语言页面。为了实现这一点，你需要留空默认的语言目录 (/)，并在插件选项中设置 autoLocale: true。插件会自动根据用户语言跳转到对应的语言页面。

也就是你需要设置以下目录结构:

.
├── en
│   ├── ...
│   ├── page.md
│   └── README.md
├── zh
│   ├── ...
│   ├── page.md
│   └── README.md
└── other_languages
    ├── ...
    ├── page.md
    └── README.md

并将主题选项的 locales 设置为:

export default {
  locales: {
    '/en/': {
      lang: 'en-US',
      // ...
    },
    '/zh/': {
      lang: 'zh-CN',
      // ...
    },
    // other languages
  },
  // ...
}

这样当用户访问 / 或 /page.html 时，他们会自动根据当前浏览器语言重定向到 /en/ /en/page.html 与 /zh/ /zh/page.html。

自定义回退行为

有些时候，用户可能会在系统设置中添加多个语言。默认情况下，在站点支持首选语言，但首选语言不存在相应页面时，插件会尝试匹配用户设置的备用语言。

如果不需要回退到用户备用语言，而直接匹配用户首选语言，请在插件选项中设置 localeFallback: false。

自定义缺失行为

有些时候，当用户访问一个页面时，文档尚未包含用户需要的语言版本 (一个普遍的情况是当前页面尚未完成相关语言的本地化)，这样插件需要做出默认行为，你可以通过插件选项中的 defaultBehavior 定制它:

"defaultLocale": 重定向到默认语言或首个可用语言页面 (默认行为)
"homepage": 重定向到当前语言的主页 (仅在文档包含用户语言时可用)
"404": 重定向到当前语言的 404 页 (仅在文档包含用户语言时可用)

自定义默认路径

你可以通过设置插件选项中的 defaultLocale 来自定义默认路径。默认情况下，插件会使用 locales 中的第一个键名作为默认路径。

自动切换语言

插件支持在多语言文档中，自动根据用户语言首选项，将链接切换到用户需要的多语言页面。为了实现这一点，你需要在插件选项中设置 switchLocale，它可以是以下两个值:

direct: 直接切换到用户语言首选项页面，而不询问
modal: 在用户语言首选项与当前页面语言不同时，弹出一个对话框询问用户是否切换语言

自定义多语言配置

默认情况下，插件会从站点的多语言配置 locales 选项中，读取 语言路径 和 lang 生成多语言配置。有些时候，你可能希望多个语言命中同一个路径，这种情况下，你应该设置插件的 localeConfig 选项。

比如，你可能希望所有英文用户都匹配到 /en/，并将繁体中文用户匹配到 /zh/ 中，那么你可以设置:

redirect({
  localeConfig: {
    '/en/': ['en-US', 'en-UK', 'en'],
    '/zh/': ['zh-CN', 'zh-TW', 'zh'],
  },
})

重定向站点

有时你可能会更改 base 或为你的站点使用新域名，因此你可能希望原始站点自动重定向到新站点。

为了解决这个问题，插件提供了 vp-redirect 脚手架。

使用: vp-redirect [选项] <源文件夹> [输出文件夹]

为当前 VuePress 项目生成重定向站点

Generate redirect site for current VuePress project

参数：
  源文件夹                 VuePress 项目的源文件夹
  输出文件夹               输出文件夹 (默认: .vuepress/redirect 相对于源文件夹)

选项：
  --hostname <hostname>  重定向到的域名 (例如: https://new.example.com/) (默认: /)
  -c, --config [config]  设置配置文件路径
  --cache [cache]        设置缓存文件的目录
  --temp [temp]          设置临时文件的目录
  --clean-cache          生成前清理缓存文件
  --clean-temp           生成前清理临时文件
  -V, --version          输出版本号
  -h, --help             显示帮助信息

你需要传入 VuePress 项目源目录并设置 hostname 选项。重定向助手脚手架将初始化你的 VuePress 项目以获取页面，然后在输出目录生成重定向 html 文件。

默认情况下，插件将输出到源文件夹下的 .vuepress/redirect 目录。你应该将其上传到你的原始站点以提供重定向。

选项

configRecord<string, string> | ((app: App) => Record<string, string>)

页面重定向映射。键名为重定向的源页面地址，键值为重定向的目标地址。

参考：设置重定向。

autoLocaleboolean

是否启用语言重定向。

参考：自动多语言。

switchLocale'direct' | 'modal' | 'popup' | false

默认值false

是否根据用户偏好切换到新的语言环境。

'direct': 直接重定向到新的语言环境而不询问。
'popup': 显示一个弹窗让用户选择是否切换到新的语言环境。
'modal': 显示一个全屏模态框让用户选择是否切换到新的语言环境。

参考：自动切换语言。

localeConfigRecord<string, string[] | string>

多语言语言配置。

参考：自定义多语言配置。

localeFallbackboolean

默认值true

是否回退到用户定义的其他语言。

defaultBehavior'404' | 'defaultLocale' | 'homepage'

默认值'defaultLocale'

当前链接没有可用的语言版本时的行为。

'defaultLocale': 重定向到默认语言或首个可用语言页面。
'homepage': 重定向到当前语言的主页。仅当语言分配给当前语言时可用。
'404': 重定向到当前语言的 404 页。仅当语言分配给当前语言时可用。

defaultLocalestring

默认值首个语言路径

默认语言路径。如果缺失，则使用第一个语言。

localesLocaleConfig<RedirectPluginLocaleData>

重定向插件的国际化配置，各语言的数据为 RedirectPluginLocaleData 的一部分。

参考：多语言配置。

locales.<localePath>.namestring

语言名称。

locales.<localePath>.hintstring

切换提示。

locales.<localePath>.switchstring

切换按钮文字。

locales.<localePath>.cancelstring

取消按钮文字。

locales.<localePath>.rememberstring

记住提示文本。

Frontmatter

redirectFromstring | string[]

重定向到该页面的地址。

参考：设置重定向。

redirectTostring

该页面重定向到的地址。

参考：设置重定向。

样式

你可以通过 CSS 变量来自定义重定向弹窗的样式：

:root {
  --redirect-z-index: 1499;
  --redirect-c-bg: var(--vp-c-bg-elv);
  --redirect-c-text: var(--vp-c-text);
  --redirect-c-accent-bg: var(--vp-c-accent-bg);
  --redirect-c-accent-hover: var(--vp-c-accent-hover);
  --redirect-c-accent-text: var(--vp-c-accent-text);
  --redirect-c-control: var(--vp-c-control);
  --redirect-c-control-hover: var(--vp-c-control-hover);
  --redirect-c-shadow: var(--vp-c-shadow);
}