redirect

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

使用方法

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

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

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

设置重定向

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

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

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

自动多语言

插件可以根据用户的语言首选项，自动将无多语言链接重定向到用户需要的多语言页面。为了实现这一点，你需要留空默认的语言目录 (/)，并在插件选项中设置 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。

自动切换语言

插件支持在多语言文档中，自动根据用户语言首选项，将链接切换到用户需要的多语言页面。为了实现这一点，你需要在插件选项中设置 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 目录。你应该将其上传到你的原始站点以提供重定向。

选项

config

• 类型：Record<string, string> | ((app: App) => Record<string, string>)

• 详情

  页面重定向映射。

  可直接传入对象或传入参数为 App 的函数返回值一个对象。

  每个键名必须是一个绝对路径，代表重定向的源页面地址。

  每个键值是重定向的目标地址，可以是绝对路径或完整路径。

• 示例：

  当 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

• 类型：boolean
• 默认值：false
• 详情： 是否启用语言重定向

switchLocale

• 类型："direct" | "modal" | false

• 默认值：false

• 详情：

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

  • "direct": 直接重定向到新的语言环境而不询问
  • "modal": 显示一个模式让用户选择是否切换到新的语言环境

localeConfig

• 类型：Record<string, string | string[]>
• 详情：多语言语言配置

localeFallback

• 类型：boolean
• 默认值：true
• 详情：是否回退到用户定义的其他语言

defaultBehavior

• 类型："defaultLocale" | "homepage" | "404"
• 默认值："defaultLocale"
• 详情：当前链接没有可用的语言版本时的行为

defaultLocale

• 类型：string
• 默认值：首个语言路径
• 详情：默认语言路径

locales

• 类型：RedirectPluginLocaleConfig

  interface RedirectPluginLocaleData {
    /**
     * 语言名称
     */
    name: string
  
    /**
     * 切换提示
     */
    hint: string
  
    /**
     * 切换按钮文字
     */
    switch: string
  
    /**
     * 取消按钮文字
     */
    cancel: string
  
    /**
     * 记住提示文本
     */
    remember: string
  }
  
  interface RedirectPluginLocaleConfig {
    [localePath: string]: Partial<RedirectPluginLocaleData>
  }

• 详情：

  重定向插件的国际化配置。

Frontmatter

redirectFrom

• 类型：string | string[]
• 详情：重定向到该页面的地址。

redirectTo

• 类型：string
• 详情：该页面重定向到的地址。

样式

你可以通过 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);
}