分析 WordPress `wp_get_document_title()` 函数的源码：页面标题的生成逻辑与相关过滤器。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位观众老爷，早上好！今天咱们来聊聊WordPress的wp_get_document_title()函数，这个家伙可是网页标题的幕后英雄，关系到SEO、用户体验，甚至老板的心情。咱们不搞那些高深莫测的理论，直接扒开它的源码，看看它是怎么工作的，以及我们怎么利用它来让我们的网站更上一层楼。

一、开场白：网页标题的重要性

在互联网世界里，网页标题就像人的脸，是给用户的第一印象。一个好的标题能吸引眼球，提高点击率，让搜索引擎更容易找到你。WordPress默认的标题生成方式可能不能满足所有需求，所以我们需要了解wp_get_document_title()，才能更好地掌控我们的网站标题。

二、wp_get_document_title()函数概览

这个函数的主要职责是生成并返回当前页面的标题。它会根据不同的页面类型（首页、文章页、分类页等）采用不同的标题生成策略。更重要的是，它还提供了多个过滤器，允许我们自定义标题，简直是良心设计。

三、源码剖析：一层一层揭开它的面纱

我们直接进入wp-includes/general-template.php，找到wp_get_document_title()函数的定义。为了方便理解，我把它简化了一下，去掉了不常用的部分，然后加上了详细的注释：

/**
 * Retrieves the document title.
 *
 * @since 4.4.0
 *
 * @return string The page title.
 */
function wp_get_document_title() {
    global $wp_query;

    // 初始化标题，默认为站点名称
    $title = get_bloginfo( 'name', 'display' );

    // 获取站点描述，用于首页标题
    $site_description = get_bloginfo( 'description', 'display' );

    // 根据不同的页面类型生成标题
    if ( is_front_page() || is_home() ) {
        // 首页或博客页
        if ( $site_description && ( is_home() || is_front_page() ) ) {
            $title = sprintf( '%1$s %2$s %3$s', $title, apply_filters( 'document_title_separator', '|' ), $site_description );
        }
    } elseif ( is_singular() ) {
        // 文章页或页面
        $title = single_post_title( '', false );
    } elseif ( is_category() ) {
        // 分类页
        $title = single_cat_title( '', false );
    } elseif ( is_tag() ) {
        // 标签页
        $title = single_tag_title( '', false );
    } elseif ( is_tax() ) {
        // 分类法页面
        $term = get_queried_object();
        if ( $term ) {
            $title = sprintf( __( '%1$s Archives' ), single_term_title( '', false ) );
        }
    } elseif ( is_post_type_archive() ) {
        // 文章类型归档页
        $title = post_type_archive_title( '', false );
    } elseif ( is_author() ) {
        // 作者页
        $title = get_the_author();
    } elseif ( is_search() ) {
        // 搜索结果页
        $title = sprintf( __( 'Search Results for: %s' ), get_search_query() );
    } elseif ( is_404() ) {
        // 404页面
        $title = __( 'Page Not Found' );
    } else {
        // 其他页面，使用站点名称
        $title = get_bloginfo( 'name', 'display' );
    }

    /**
     * Filters the document title.
     *
     * @since 4.4.0
     *
     * @param string $title The document title.
     */
    $title = apply_filters( 'wp_title', $title, '|' ); // 兼容旧的wp_title过滤器

    /**
     * Filters the document title.
     *
     * @since 4.4.0
     *
     * @param string $title The document title.
     */
    $title = apply_filters( 'pre_get_document_title', $title );

    /**
     * Filters the document title.
     *
     * @since 4.4.0
     *
     * @param string $title The document title.
     */
    $title = apply_filters( 'get_document_title', $title );

    return $title;
}

代码解读：

初始化： 首先，它会获取你的站点名称(get_bloginfo( 'name', 'display' ))作为标题的基础。
页面类型判断： 接下来，它会根据不同的页面类型，使用不同的函数来生成标题。例如，single_post_title()用于文章页，single_cat_title()用于分类页，等等。
过滤器： 最后，它会应用三个过滤器：wp_title（为了兼容旧版本）、pre_get_document_title和get_document_title。这三个过滤器允许我们修改最终的标题。

四、页面类型与标题生成逻辑：一张表格搞定

为了更清晰地展示不同页面类型的标题生成逻辑，我做了一张表格：

页面类型	标题生成函数/逻辑
首页/博客页	`get_bloginfo( 'name', 'display' )` + 分隔符 + `get_bloginfo( 'description', 'display' )`
文章页/页面	`single_post_title( '', false )`
分类页	`single_cat_title( '', false )`
标签页	`single_tag_title( '', false )`
分类法页面	`single_term_title( '', false )` (如果存在) + "Archives"
文章类型归档页	`post_type_archive_title( '', false )`
作者页	`get_the_author()`
搜索结果页	"Search Results for: " + `get_search_query()`
404页	"Page Not Found"
其他页面	`get_bloginfo( 'name', 'display' )`

五、过滤器的妙用：打造独一无二的标题

重点来了！wp_get_document_title()提供了三个过滤器，让我们能够灵活地修改标题。这就像给了一个万能钥匙，可以打开各种自定义标题的大门。

pre_get_document_title： 这是第一个过滤器，在任何默认标题生成之前执行。如果你想完全控制标题，可以用这个过滤器直接返回你想要的标题。
get_document_title： 这是最后一个过滤器，在所有默认标题生成之后执行。你可以用这个过滤器修改最终的标题，比如添加一些后缀或前缀。
wp_title： 为了兼容旧版本的WordPress主题和插件，这个过滤器仍然存在。它和get_document_title的功能类似，但使用方式略有不同。传递了分隔符参数。

示例代码：

假设你想在所有文章页的标题后面加上" – 我的网站"，你可以这样写：

add_filter( 'get_document_title', 'my_custom_document_title' );

function my_custom_document_title( $title ) {
    if ( is_singular( 'post' ) ) { // 仅对文章页生效
        $title .= ' - 我的网站';
    }
    return $title;
}

这段代码放在你主题的functions.php文件里，或者放在一个自定义插件里都可以。

再来一个例子，如果你想完全自定义首页的标题，可以这样写：

add_filter( 'pre_get_document_title', 'my_custom_front_page_title' );

function my_custom_front_page_title( $title ) {
    if ( is_front_page() ) {
        $title = '欢迎来到我的超酷网站！';
    }
    return $title;
}

六、实战演练：几个常见的标题优化场景

现在，我们来结合一些实际场景，看看如何利用wp_get_document_title()和过滤器来优化网站标题。

场景1：在分类页标题中添加分类描述

WordPress默认的分类页标题只显示分类名称，如果能加上分类描述，就能更好地吸引用户和搜索引擎。

add_filter( 'get_document_title', 'my_custom_category_title' );

function my_custom_category_title( $title ) {
    if ( is_category() ) {
        $category_description = strip_tags( category_description() ); // 获取分类描述，并去除HTML标签
        if ( ! empty( $category_description ) ) {
            $title = sprintf( '%1$s - %2$s', $title, $category_description );
        }
    }
    return $title;
}

场景2：为文章页添加SEO关键词

虽然WordPress本身没有直接提供添加SEO关键词的功能，但我们可以通过插件或者自定义代码来实现。这里我们用get_post_meta()函数获取文章的自定义字段，然后添加到标题中。

add_filter( 'get_document_title', 'my_custom_post_title' );

function my_custom_post_title( $title ) {
    if ( is_singular( 'post' ) ) {
        $keywords = get_post_meta( get_the_ID(), 'seo_keywords', true ); // 获取名为"seo_keywords"的自定义字段
        if ( ! empty( $keywords ) ) {
            $title = sprintf( '%1$s - %2$s', $title, $keywords );
        }
    }
    return $title;
}

注意： 使用这种方法需要先在文章的编辑页面添加一个名为"seo_keywords"的自定义字段，并填写关键词。当然，你也可以使用现成的SEO插件来管理关键词，然后通过插件提供的函数来获取关键词。

场景3：根据用户角色显示不同的标题

有时候，我们可能需要根据用户的角色来显示不同的标题。比如，对于管理员，我们可能想在标题中添加一些调试信息。

add_filter( 'get_document_title', 'my_custom_role_title' );

function my_custom_role_title( $title ) {
    if ( current_user_can( 'administrator' ) ) { // 判断当前用户是否是管理员
        $title = '[管理员] ' . $title;
    }
    return $title;
}

七、总结与注意事项

wp_get_document_title()是WordPress生成网页标题的核心函数，了解它的工作原理可以帮助我们更好地控制网站标题。
利用pre_get_document_title和get_document_title这两个过滤器，我们可以轻松地自定义标题，满足各种需求。
在修改标题时，要考虑到SEO因素，尽量使用关键词，但不要过度堆砌。
注意代码的兼容性，尽量使用WordPress提供的函数和API，避免出现意外错误。
在修改主题的functions.php文件时，最好先备份一下，以防万一。

八、更进一步：使用插件简化操作

如果你觉得手动编写代码太麻烦，也可以使用一些现成的WordPress插件来管理网站标题。这些插件通常提供了更友好的用户界面，可以让你更方便地设置标题和关键词。一些常见的SEO插件，如Yoast SEO、Rank Math等，都提供了强大的标题管理功能。

九、Q&A环节：解答你的疑惑

Q：wp_title()和wp_get_document_title()有什么区别？

A：wp_title()是旧版本的函数，现在已经被wp_get_document_title()取代。wp_get_document_title()更加灵活，提供了更多的过滤器，并且能够更好地处理不同页面类型的标题。wp_title()主要用于在模板文件中直接输出标题，而wp_get_document_title()主要用于获取标题，然后你可以根据需要进行处理。
Q：我可以直接修改WordPress的核心文件吗？

A：强烈不建议！直接修改核心文件会导致升级困难，并且容易出现各种问题。你应该使用主题或插件来修改网站的功能。
Q：如何调试我的自定义标题代码？

A：可以使用var_dump()或error_log()函数来输出变量的值，看看代码是否按照你的预期执行。另外，可以开启WordPress的调试模式，查看是否有错误提示。
Q：修改标题后，搜索引擎需要多久才能更新？

A：这取决于搜索引擎的抓取频率和更新速度。一般来说，几天到几周不等。你可以使用Google Search Console等工具来加快更新速度。

好了，今天的讲座就到这里。希望大家能够掌握wp_get_document_title()的用法，打造出更加优秀的WordPress网站！感谢各位的收看，我们下期再见！

发表回复 取消回复

发表回复取消回复