README

已弃用

此 Craft CMS 2.x 插件不再受支持，但它完全功能正常，您可以根据需要继续使用它。许可证还允许您根据对旧版支持的需要进行分叉并进行更改。

此插件的 Craft CMS 3.x 版本可在此处找到：craft-retour，并且也可以通过 Craft CP 中的 Craft 插件商店安装。

Craft CMS 插件 Retour

Retour 允许您智能地重定向旧版 URL，在重建和重新构建网站结构时不会丢失 SEO 价值。

相关：Craft 3.x 的 Retour

安装

要安装 Retour，请按照以下步骤操作

1. 下载并解压缩文件，并将 retour 目录放入您的 craft/plugins 目录
2. -OR- 直接在 craft/plugins 文件夹中执行 git clone https://github.com/nystudio107/retour.git。然后您可以使用 git pull 更新它
3. -OR- 通过 Composer 使用 composer require nystudio107/retour 安装
4. 在 Craft 控制面板下的设置 > 插件中安装插件
5. 插件文件夹应命名为 retour，以便 Craft 能够识别。GitHub 最近开始将 -master（分支名称）添加到下载 zip 文件的文件夹名称中。

Retour 在 Craft 2.4.x、Craft 2.5.x 和 Craft 2.6.x 上工作。

Retour 概览

Retour 允许您智能地重定向旧版 URL，在重建和重新构建网站结构时不会丢失 SEO 价值。

除了支持传统的精确和 RegEx 匹配 URL 模式外，Retour 还有一个可以添加到您条目中的 Retour Redirect FieldType。这允许您在匹配 URL 模式时访问条目中的数据，以实现动态条目重定向。

如果您更改条目的 slug 或在结构中移动条目，Retour 还会自动为您创建重定向。

Retour 编写以性能为导向。只有在发生 404 异常时，您的网站性能才会受到影响；即使在这种情况下，匹配的结果也具有最小的影响。

不要只是重建网站。使用 Retour 进行过渡。

为什么使用重定向插件？

如果您只有少量静态重定向，那么将它们放入 .htaccess 文件中是您的最佳选择，或者更好的是，放入您的虚拟主机的 .conf 文件中。但是，在某些情况下，使用插件来处理它是一个更好的解决方案。

1. 如果您有很多重定向，如果它们在 .htaccess 或 .conf 中，则会减慢您的 web 服务器处理的每个请求。
2. 通常，来自旧网站的 URL 模式不会以确定性的方式与新网站的 URL 匹配，这使得创建重定向变得困难。
3. 有时您无法访问服务器配置文件，或者您想给客户轻松管理重定向的能力。

Retour 解决了这些问题。

1. Retour 仅在 web 服务器已抛出 404 异常后尝试重定向。一旦成功确定重定向映射，它还会缓存结果以快速解决下一个重定向请求。
2. Retour 还为您提供了动态入口重定向的功能，允许您将一些旧数据导入到您的入口中，用作确定新URL映射的键。这样，可以有效地为完全不同的URL进行重定向。
3. 它提供了一个易于使用的GUI，客户端可以从Craft的AdminCP使用，并记录404击中（和错过）的统计信息。

关于 .htaccess 的说明

使用Apache网络服务器的用户熟悉 .htaccess 文件，甚至可能正在使用它进行重定向。您很可能根本不应该使用 .htaccess；相反，您应该通过 AllowOverride none 禁用 .htaccess 并在您的网络服务器配置文件中更改您的配置。请参阅 Apache HTTP服务器教程：.htaccess 文件

There are two main reasons to avoid the use of .htaccess files.

The first of these is performance. When AllowOverride is set to allow the
use of .htaccess files, httpd will look in every directory for .htaccess
files. Thus, permitting .htaccess files causes a performance hit, whether or
not you actually even use them! Also, the .htaccess file is loaded every
time a document is requested.

Further note that httpd must look for .htaccess files in all higher-level
directories, in order to have a full complement of directives that it must
apply. (See section on how directives are applied.) Thus, if a file is
requested out of a directory /www/htdocs/example, httpd must look for the
following files:

/.htaccess
/www/.htaccess
/www/htdocs/.htaccess
/www/htdocs/example/.htaccess

And so, for each file access out of that directory, there are 4 additional
file-system accesses, even if none of those files are present. (Note that
this would only be the case if .htaccess files were enabled for /, which is
not usually the case.)

In the case of RewriteRule directives, in .htaccess context these regular
expressions must be re-compiled with every request to the directory, whereas
in main server configuration context they are compiled once and cached.
Additionally, the rules themselves are more complicated, as one must work
around the restrictions that come with per-directory context and
mod_rewrite. Consult the Rewrite Guide for more detail on this subject.

如您所见，如果可能的话，完全避免使用 .htaccess 是最好的，特别是避免用于 RewriteRule 指令，如404重写。

动态入口重定向

Retour 实现了一个可以添加到您的入口类型的 Retour Redirect 字段类型。Retour 将查找匹配旧URL模式的 404（未找到）URL，并将它们重定向到该入口的URL。

您还可以获取 entry 的上下文，您可以在匹配旧URL时使用它；因此，如果您已将名为 recipeid 的字段导入到您的新网站中，您可以使用 Retour Redirect 字段类型在旧URL模式中查找它，例如： /old-recipes/{recipeid}

这允许您基于导入的旧数据来设置键，当新URL模式与旧URL模式完全不同，或者需要正则表达式来匹配任何模式时，这很有用。

创建 Retour 重定向字段

就像创建其他任何字段一样创建 Retour 重定向字段；然后设置其默认值。对于新条目，它将默认到此处输入的值，因此您可以一次性放置匹配模式，而不是为每个条目都进行操作。

• 默认旧URL模式 - 输入 Retour 应匹配的URL模式。这与路径匹配，即URL域名之后的URL部分。您可以在下面的文本字段中包含输出条目标识的标签，如 {title} 或 {myCustomField}。例如：精确匹配： /recipes/{recipeid} 或正则表达式匹配： .*RecipeID={recipeid}$ 其中 {recipeid} 是指向此条目中字段的字段名称。
• 默认模式匹配类型 - 应使用何种类型与旧URL模式进行匹配。有关正则表达式匹配的详细信息，请参阅 regexr.com。如果插件提供了自定义匹配函数，您可以在此处选择它。
• 默认重定向类型 - 选择重定向是永久性的还是临时的。
• 重定向可更改 - 是否允许用户在编辑条目时更改重定向。

配置 Retour 重定向字段

• 旧URL模式 - 输入 Retour 应匹配的URL模式。这与路径匹配，即URL域名之后的URL部分。您可以在下面的文本字段中包含输出条目标识的标签，如 {title} 或 {myCustomField}。例如：精确匹配： /recipes/{recipeid} 或正则表达式匹配： .*RecipeID={recipeid}$ 其中 {recipeid} 是指向此条目中字段的字段名称。
• 模式匹配类型 - 应使用何种类型与旧URL模式进行匹配。有关正则表达式匹配的详细信息，请参阅 regexr.com。如果插件提供了自定义匹配函数，您可以在此处选择它。
• 重定向类型 - 选择重定向是永久性的还是临时的。

注意：如果您向现有部分添加一个Retour重定向字段类型，或者将来自外部源的数据导入具有Retour重定向字段类型的部分，则您为Retour重定向字段类型设置的默认值将不会传播到条目。要使此操作发生，请转到设置->部分，然后点击要编辑的部分，并点击保存。这将导致该部分的所有条目重新保存，并且Retour将填写默认字段值。

静态重定向

手动创建静态重定向

当旧URL模式和新的URL模式是确定性的时，静态重定向很有用。您可以通过点击Retour->重定向，然后点击+ 新建静态重定向按钮来创建它们。

• 旧URL模式 - 输入Retour应匹配的URL模式。这匹配路径，即域名之后的URL部分。例如：精确匹配：/recipes/ 或正则表达式匹配：.*RecipeID=(.*)
• 目标URL - 输入应重定向到的目标URL。这可以是完全限定的URL或相对URL。例如：精确匹配：/new-recipes/ 或正则表达式匹配：/new-recipes/$1
• 模式匹配类型 - 应使用何种类型与旧URL模式进行匹配。有关正则表达式匹配的详细信息，请参阅 regexr.com。如果插件提供了自定义匹配函数，您可以在此处选择它。
• 重定向类型 - 选择重定向是永久性的还是临时的。

导入现有的 .htaccess 文件

Retour还允许您通过点击Retour->重定向，然后点击导入 .htaccess 文件按钮，将现有的.htaccess文件及其包含的所有重定向导入Retour。

它将导入文件中的Redirect和RedirectMatch指令的重定向。它将忽略RewriteRule，因为它们不一定有1:1的映射，您可能有多个RewriteRule连续使用以确定最终的跳转。

它要求您的浏览器仅查找text文件进行上传；如果您有的.htaccess文件不是.txt文件，您可以通过选择格式：所有文件来强制它允许您上传。

重命名别名重定向

如果您重命名了条目的slug（并且条目所在的部分有URL），Retour将自动为您创建一个静态重定向，以保持流量流向正确的位置。如果您在结构中移动条目，它也会自动创建一个静态重定向。

它将像任何其他静态重定向一样列在“静态重定向”部分下。

Retour统计

Retour会跟踪您的网站收到的每个404错误。您可以通过点击Retour->统计来查看它们。

每个URL模式只保存一条记录，因此数据库不会因大量记录而拥堵。

Retour小部件

如果您想在仪表板上查看Retour统计的概述，您可以将Retour小部件添加到您的仪表板

它显示处理和未处理的404总数，以及每个类别中最新的5个404 URL，直接显示在您的仪表板上。

开发者信息

通过插件实现自定义匹配函数

如果精确匹配和正则表达式匹配不足以满足您的需求，Retour允许您通过插件实现自定义匹配函数。

在您的主要插件类文件中，只需添加此函数

/**
 * retourMatch gives your plugin a chance to use whatever custom logic is needed for URL redirection.  You are passed
 * in an array that contains the details of the redirect.  Do whatever matching logic, then return true if is a
 * matched, false if it is not.
 *
 * You can alter the 'redirectDestUrl' to change what URL they should be redirected to, as well as the 'redirectHttpCode'
 * to change the type of redirect.  None of the changes made are saved in the database.
 *
 * @param mixed An array of arguments that define the redirect
 *            $args = array(
 *                'redirect' => array(
 *                    'id' => the id of the redirect record in the retour_redirects table
 *                    'associatedElementId' => the id of the entry if this is a Dynamic Entry Redirect; 0 otherwise
 *                    'redirectSrcUrl' => the legacy URL as entered by the user
 *                    'redirectSrcUrlParsed' => the redirectSrcUrl after it has been parsed as a micro template for {variables}
 *                        via renderObjectTemplate().  This is typically what you would want to match against.
 *                    'redirectMatchType' => the type of match; this will be set to your plugin's ClassHandle
 *                    'redirectDestUrl' => the destination URL for the entry this redirect is associated with, or the
 *                        destination URL that was manually entered by the user
 *                    'redirectHttpCode' => the redirect HTTP code (typically 301 or 302)
 *                    'hitCount' => the number of times this redirect has been matched, and the redirect done in the browser
 *                    'hitLastTime' => the date and time of the when this redirect was matched
 *                    'locale' => the locale of this redirect
 *                )
 *            );
 * @return bool Return true if it's a match, false otherwise
 */
public function retourMatch($args)
{
    return true;
}

您的插件将出现在可以通过Retour->重定向或Retour重定向字段类型选择的模式匹配类型列表中。

实用函数

在您的模板中，craft.retour.getHttpStatus将返回当前模板的HTTP状态代码，因此您可以显示针对通过301或302重定向到达页面的用户的特殊消息。

Retour路线图

要完成的事情以及潜在功能的想法

• Craft 3 兼容性
• 添加从CSV文件批量导入重定向的能力

由nystudio107提供