深入理解 `template_redirect` 钩子的源码，它是如何判断当前请求的模板并将其加载的？

WordPress 模板跳转钩子 template_redirect：源码解剖与实战演练 (讲座)

大家好，我是你们今天的导游，将带领大家深入 WordPress 的神秘丛林，探索 template_redirect 钩子的奥秘。准备好了吗？ 咱们这就出发！

第一站：template_redirect 钩子概览

template_redirect 是 WordPress 中一个非常重要的动作钩子 (action hook)，它在 WordPress 加载模板文件之前被触发。简单来说，它就像一个交通警察，负责检查当前的请求，然后决定应该加载哪个模板文件来渲染页面。

这个钩子的触发时间点非常关键，因为它允许我们在 WordPress 决定最终的模板之前进行干预。我们可以利用它来：

• 自定义模板选择逻辑
• 重定向到其他页面
• 执行一些需要在模板加载前完成的任务

第二站：template_redirect 的触发点

template_redirect 钩子是在 wp() 函数中被触发的，而 wp() 函数又是 WordPress 加载流程的核心部分。让我们来看看相关的源码片段 (位于 wp-includes/template-loader.php):

<?php
/**
 * Loads the correct template based on the visitor's request.
 *
 * @since 1.5.0
 *
 * @global WP_Query $wp_query WordPress Query object.
 */
function template_redirect() {
    global $wp_query;

    /**
     * Fires immediately before WordPress loads a template file.
     *
     * @since 1.5.0
     */
    do_action( 'template_redirect' );

    // ... (后续的模板加载逻辑)
}

看到了吗？ do_action( 'template_redirect' ); 这一行就是触发这个钩子的关键。这意味着任何绑定到 template_redirect 的函数都会在这里被执行。

第三站：WordPress 如何判断模板：template_include 过滤器

虽然 template_redirect 本身不直接负责加载模板，但它为我们提供了一个绝佳的修改模板选择逻辑的机会。真正负责加载模板的是 template_include 过滤器 (filter hook)。

在 template_redirect 之后，WordPress 会根据当前的请求类型 (首页、文章页、分类页等) 尝试确定合适的模板文件。这个过程涉及到一系列的条件判断和函数调用，最终会调用 template_include 过滤器。

让我们看下 template_include 相关的源码 (位于 wp-includes/template-loader.php):

<?php
/**
 * Retrieve the name of the highest priority template file that exists.
 *
 * Searches in the STYLESHEETPATH before TEMPLATEPATH so that themes which
 * inherit from a parent theme can just define one of the required template-files.
 *
 * If the template is not found in either of those, it looks in the
 * internal WP templates.
 *
 * @since 2.7.0
 *
 * @param string $template Filename of the template to locate.
 * @return string The template filename if one is located.
 */
function get_query_template( $type ) {
    $templates = array();
    $type = preg_replace( '|[^a-z0-9-]+|', '', $type );

    if ( is_embed() ) {
        $templates[] = "embed-{$type}.php";
    }
    $templates[] = "{$type}.php";

    $template = locate_template( $templates );

    /**
     * Filters the path of the query template.
     *
     * @since 2.7.0
     *
     * @param string $template The path of the template to include.
     * @param string $type     The type of query template.
     * @param array  $templates A list of possible templates.
     */
    return apply_filters( "{$type}_template", $template, $type, $templates );
}

/**
 * Loads the correct template based on the visitor's request.
 *
 * @since 1.5.0
 *
 * @global WP_Query $wp_query WordPress Query object.
 */
function template_redirect() {
    global $wp_query;

    /**
     * Fires immediately before WordPress loads a template file.
     *
     * @since 1.5.0
     */
    do_action( 'template_redirect' );

    $template = false;

    if     ( is_404()            && $template = get_404_template()            ) :
    elseif ( is_search()         && $template = get_search_template()         ) :
    elseif ( is_front_page()     && $template = get_front_page_template()     ) :
    elseif ( is_home()           && $template = get_home_template()           ) :
    elseif ( is_post_type_archive() && $template = get_post_type_archive_template() ) :
    elseif ( is_tax()            && $template = get_taxonomy_template()       ) :
    elseif ( is_attachment()     && $template = get_attachment_template()     ) :
        remove_filter('the_content', 'prepend_attachment');
        $template = get_attachment_template();
    elseif ( is_single()         && $template = get_single_template()         ) :
    elseif ( is_page()           && $template = get_page_template()           ) :
    elseif ( is_category()       && $template = get_category_template()       ) :
    elseif ( is_tag()            && $template = get_tag_template()            ) :
    elseif ( is_author()         && $template = get_author_template()         ) :
    elseif ( is_date()           && $template = get_date_template()           ) :
    elseif ( is_archive()        && $template = get_archive_template()        ) :
    else :
        $template = get_index_template();
    endif;

    /**
     * Filters the path of the current template before including it.
     *
     * @since 3.0.0
     *
     * @param string $template The path of the template to include.
     */
    $template = apply_filters( 'template_include', $template );

    if ( validate_file( $template ) > 0 ) {
        return;
    }

    /**
     * Fires immediately before including the template.
     *
     * @since 1.5.0
     *
     * @param string $template The path to the template about to be included.
     */
    do_action( 'template_include_before', $template );

    include( $template );

    /**
     * Fires immediately after including the template.
     *
     * @since 2.0.0
     *
     * @param string $template The path to the template about to be included.
     */
    do_action( 'template_include_after', $template );
}

可以看到，WordPress 首先会根据各种条件判断函数 (is_404(), is_home(), is_single() 等) 来确定请求的类型，然后调用相应的 get_*_template() 函数来获取可能的模板文件路径。

这些 get_*_template() 函数内部会调用 locate_template() 函数，该函数会在主题目录中查找指定的模板文件。如果找到了，就返回模板文件的路径；否则，返回空字符串。

最后，apply_filters( 'template_include', $template ); 这一行代码应用了 template_include 过滤器。这意味着我们可以通过绑定函数到 template_include 过滤器来修改最终的模板文件路径。

第四站：实战演练：自定义模板选择

现在，让我们通过一个实际的例子来演示如何使用 template_redirect 钩子来自定义模板选择逻辑。

假设我们想要为特定的文章 ID 使用不同的模板。我们可以这样做：

<?php
/**
 * 根据文章 ID 选择不同的模板.
 *
 * @param string $template 当前的模板路径.
 *
 * @return string 修改后的模板路径.
 */
function my_custom_template( $template ) {
    if ( is_single() ) {
        global $post;

        if ( $post->ID == 123 ) {
            // 如果文章 ID 是 123, 使用 'single-custom.php' 模板.
            $custom_template = locate_template( 'single-custom.php' );
            if ( ! empty( $custom_template ) ) {
                return $custom_template;
            }
        } elseif ( $post->ID == 456 ) {
            // 如果文章 ID 是 456, 使用 'single-another.php' 模板.
            $custom_template = locate_template( 'single-another.php' );
            if ( ! empty( $custom_template ) ) {
                return $custom_template;
            }
        }
    }

    return $template; // 否则, 使用默认的模板.
}
add_filter( 'template_include', 'my_custom_template' );

这段代码首先检查当前是否为文章页 (is_single())。如果是，它会获取当前文章的 ID，然后根据 ID 的值来选择不同的模板文件。如果文章 ID 是 123，它会尝试加载 single-custom.php 模板；如果文章 ID 是 456，它会尝试加载 single-another.php 模板。如果找不到指定的模板文件，或者文章 ID 不是 123 或 456，它会返回默认的模板路径。

要让这段代码生效，你需要将它添加到你的主题的 functions.php 文件中，或者创建一个自定义的插件。

第五站：更高级的用法：重定向

除了修改模板选择逻辑，template_redirect 还可以用来重定向用户到其他页面。例如，我们可以根据用户的角色来重定向到不同的页面：

<?php
/**
 * 根据用户角色重定向到不同的页面.
 */
function my_redirect_by_role() {
    if ( is_user_logged_in() ) {
        $user = wp_get_current_user();
        if ( in_array( 'administrator', (array) $user->roles ) ) {
            // 如果是管理员, 重定向到管理面板.
            wp_safe_redirect( admin_url() );
            exit;
        } elseif ( in_array( 'subscriber', (array) $user->roles ) ) {
            // 如果是订阅者, 重定向到个人资料页面.
            wp_safe_redirect( get_edit_user_link() );
            exit;
        }
    }
}
add_action( 'template_redirect', 'my_redirect_by_role' );

这段代码首先检查用户是否已登录。如果是，它会获取当前用户的角色，然后根据角色来重定向到不同的页面。如果是管理员，它会重定向到管理面板；如果是订阅者，它会重定向到个人资料页面。

请注意，在执行重定向之后，一定要调用 exit; 来终止脚本的执行，否则可能会导致页面加载错误。

第六站：template_redirect 的执行顺序

需要注意的是，template_redirect 钩子是在 WordPress 加载模板之前被触发的。这意味着我们可以使用它来执行一些需要在模板加载前完成的任务，例如：

• 设置全局变量
• 初始化插件
• 检查用户权限

但是，我们不能在 template_redirect 钩子中输出任何 HTML 内容，因为此时 WordPress 还没有开始渲染页面。如果需要在模板中输出内容，应该使用其他的钩子，例如 the_content 或 wp_footer。

第七站：template_redirect 与其他钩子的关系

template_redirect 钩子与 WordPress 中的其他钩子有着密切的关系。例如，它通常与 template_include 过滤器一起使用，以自定义模板选择逻辑。

此外，template_redirect 钩子还可以与其他的动作钩子和过滤器钩子一起使用，以实现更复杂的功能。例如，我们可以使用 wp_head 钩子来添加自定义的 CSS 样式，或者使用 the_content 过滤器来修改文章的内容。

第八站：注意事项

在使用 template_redirect 钩子时，需要注意以下几点：

• 确保你的代码不会导致无限循环。例如，如果你的代码总是重定向到同一个页面，就会导致浏览器崩溃。
• 避免在 template_redirect 钩子中执行耗时的操作，因为这会影响页面的加载速度。
• 在执行重定向之后，一定要调用 exit; 来终止脚本的执行。
• 不要在 template_redirect 钩子中输出任何 HTML 内容。

第九站：总结

template_redirect 钩子是 WordPress 中一个非常强大的工具，它可以让我们自定义模板选择逻辑、重定向用户到其他页面、以及执行一些需要在模板加载前完成的任务。

理解 template_redirect 钩子的工作原理，可以帮助我们更好地控制 WordPress 的行为，从而实现更复杂、更强大的功能。

钩子名称	类型	触发时机	主要作用
template_redirect	动作钩子	在 WordPress 加载模板之前	提供了一个在 WordPress 决定最终的模板之前进行干预的机会，可以用来自定义模板选择逻辑、重定向到其他页面、执行一些需要在模板加载前完成的任务。
template_include	过滤器钩子	在确定要加载的模板文件路径之后	允许修改最终的模板文件路径。可以利用它来根据特定的条件 (例如文章 ID、用户角色等) 选择不同的模板文件。

希望今天的讲座能帮助大家更好地理解 template_redirect 钩子。现在，大家可以开始尝试使用它来构建自己的 WordPress 插件和主题了！

感谢大家的参与，下次再见！