详解 WordPress `post_type_link` 过滤器源码：如何自定义文章类型的永久链接。

大家好，我是老码农，今天咱们来聊聊WordPress里一个非常有趣，但也常常被忽视的过滤器：post_type_link。

话说回来，永久链接，那是网站的门牌号啊！你家如果住“人民路1号”，总不能一会儿变成“解放路2号”吧？SEO优化、用户体验，哪个都离不开一个稳定的永久链接。

WordPress默认的永久链接规则，对普通的文章（post）和页面（page）来说，通常够用。但如果咱们用了自定义文章类型（Custom Post Type，简称 CPT），想要更灵活地控制永久链接的格式，那 post_type_link 就派上大用场了。

讲座大纲：

1. post_type_link 过滤器是啥？ 它的作用、参数，以及它在 WordPress 生命周期中的位置。
2. 默认的 CPT 永久链接机制： 了解 WordPress 默认是如何处理 CPT 永久链接的。
3. post_type_link 过滤器实战： 结合代码示例，讲解如何使用这个过滤器来修改 CPT 的永久链接。
4. 使用 rewrite 参数自定义永久链接结构： 深入探讨 CPT 注册时的 rewrite 参数，以及它和 post_type_link 的关系。
5. 常见问题与注意事项： 避坑指南，让你的自定义永久链接之路更加平坦。
6. 高级技巧： 如何使用查询变量（Query Variables）来构建更复杂的永久链接。

1. post_type_link 过滤器是啥？

post_type_link 是一个 WordPress 过滤器，允许我们修改特定文章类型的永久链接。简单来说，它就像一个“拦截器”，在 WordPress 生成永久链接之前，给你一个机会“动手动脚”，按你的意愿来改造它。

参数：

• $post_link: (string) 默认的永久链接，也就是 WordPress 原始生成的链接。
• $post: (WP_Post) 当前的文章对象。包含了文章的所有信息，比如 ID、标题、内容等等。
• $leavename: (bool) 是否保留文章名称（%postname%）在永久链接中。

用法示例：

add_filter( 'post_type_link', 'my_custom_post_type_link', 10, 3 );

function my_custom_post_type_link( $post_link, $post, $leavename ) {
    // 这里写你的代码
    return $post_link;
}

生命周期：

post_type_link 过滤器在 get_permalink() 函数内部被调用，而 get_permalink() 是 WordPress 生成文章永久链接的核心函数。这意味着，只要涉及到文章永久链接的生成，post_type_link 过滤器就有机会发挥作用。

2. 默认的 CPT 永久链接机制：

当我们注册一个自定义文章类型时，如果没有特别指定 rewrite 参数，WordPress 会使用默认的永久链接规则。

例如，我们注册一个名为 product 的 CPT：

function register_product_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Products',
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
    );
    register_post_type( 'product', $args );
}
add_action( 'init', 'register_product_post_type' );

如果没有设置 rewrite，那么默认的永久链接结构大概是这样的：

http://example.com/?post_type=product&p=123

这显然不太友好，既不利于SEO，也不方便用户记忆。

3. post_type_link 过滤器实战：

现在，让我们使用 post_type_link 过滤器来改造 product 这种 CPT 的永久链接。

假设我们想把 product 的永久链接改成这样：

http://example.com/products/产品名称/

代码如下：

add_filter( 'post_type_link', 'custom_product_permalink', 10, 3 );

function custom_product_permalink( $post_link, $post, $leavename ) {
    if ( $post->post_type == 'product' ) {
        return home_url( '/products/' . $post->post_name . '/' );
    } else {
        return $post_link;
    }
}

// 别忘了刷新固定链接结构，否则不会生效!

代码解释：

• add_filter( 'post_type_link', 'custom_product_permalink', 10, 3 );：将 custom_product_permalink 函数挂载到 post_type_link 过滤器上。
• custom_product_permalink( $post_link, $post, $leavename )：这个函数就是我们的“拦截器”。
• if ( $post->post_type == 'product' )：判断当前文章是否是 product 类型的。
• return home_url( '/products/' . $post->post_name . '/' );：如果是 product 类型的文章，就生成我们自定义的永久链接。home_url() 函数用于获取网站的根 URL，$post->post_name 包含了文章的别名（slug）。
• else { return $post_link; }: 如果不是product类型的文章，直接返回WordPress默认的链接。

重点： 在修改永久链接结构后，一定要去 WordPress 后台的 "设置" -> "固定链接" 页面，点击 "保存更改" 按钮。 这个操作会刷新 WordPress 的 rewrite 规则，让新的永久链接结构生效。 否则，你可能会看到 404 错误。

4. 使用 rewrite 参数自定义永久链接结构：

在注册 CPT 时，rewrite 参数是一个非常重要的选项。它可以让你在 CPT 层面就定义好永久链接的结构，而不需要完全依赖 post_type_link 过滤器。

rewrite 参数是一个数组，常用的选项包括：

• slug: (string) 永久链接的前缀。例如，如果 slug 设置为 products，那么永久链接就会以 /products/ 开头。
• with_front: (bool) 是否在永久链接中包含前缀。默认情况下，WordPress 会在永久链接中包含 "前缀"，这个前缀通常是你在 "设置" -> "固定链接" 页面设置的。如果 with_front 设置为 false，就可以移除这个前缀。
• feeds: (bool) 是否启用文章 Feed 功能。
• pages: (bool) 是否支持分页。

修改上面的 register_product_post_type 函数：

function register_product_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Products',
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
        'rewrite' => array( 'slug' => 'products', 'with_front' => false ),
    );
    register_post_type( 'product', $args );
}
add_action( 'init', 'register_product_post_type' );

// 别忘了刷新固定链接结构，否则不会生效!

设置了 rewrite 参数后，product 类型的文章永久链接就会变成：

http://example.com/products/产品名称/

这和我们之前使用 post_type_link 过滤器实现的效果是一样的。

rewrite vs post_type_link：

• rewrite： 在 CPT 注册时定义永久链接结构，更适合于全局性的、静态的永久链接规则。
• post_type_link： 更加灵活，可以在运行时动态地修改永久链接，适合于需要根据文章内容或其他条件来生成永久链接的场景。

一般来说，如果你的永久链接规则比较简单，直接使用 rewrite 参数就可以了。如果需要更复杂的逻辑，或者需要在运行时动态地生成永久链接，那么 post_type_link 过滤器是更好的选择。

5. 常见问题与注意事项：

• 404 错误： 修改永久链接结构后，一定要刷新固定链接设置。否则，你会遇到 404 错误。
• 冲突： 如果多个插件或主题都使用了 post_type_link 过滤器，可能会发生冲突。可以通过调整过滤器的优先级（第三个参数）来解决冲突。
• 性能： 复杂的 post_type_link 过滤器逻辑可能会影响网站的性能。尽量避免在过滤器中执行耗时的操作。
• URL 编码： 注意 URL 编码问题。文章标题或别名中可能包含特殊字符，需要进行 URL 编码，以确保永久链接的正确性。urlencode() 函数可以帮助你进行 URL 编码。

6. 高级技巧：

有时候，我们需要更复杂的永久链接结构，例如：

http://example.com/products/category/电子产品/产品名称/

在这种情况下，我们需要使用查询变量（Query Variables）。

步骤：

1. 注册查询变量： 使用 query_vars 过滤器注册自定义的查询变量。
2. 修改永久链接结构： 使用 post_type_link 过滤器，将查询变量添加到永久链接中。
3. 解析查询变量： 使用 template_include 动作，根据查询变量的值来加载相应的模板。

代码示例：

// 1. 注册查询变量
add_filter( 'query_vars', 'add_product_category_query_var' );
function add_product_category_query_var( $vars ) {
    $vars[] = 'product_category';
    return $vars;
}

// 2. 修改永久链接结构
add_filter( 'post_type_link', 'custom_product_permalink_with_category', 10, 3 );

function custom_product_permalink_with_category( $post_link, $post, $leavename ) {
    if ( $post->post_type == 'product' ) {
        // 假设你有一个名为 "product_category" 的自定义字段，用于存储产品分类
        $category = get_post_meta( $post->ID, 'product_category', true );
        if ( ! empty( $category ) ) {
            return home_url( '/products/category/' . $category . '/' . $post->post_name . '/' );
        } else {
            return home_url( '/products/' . $post->post_name . '/' );
        }
    } else {
        return $post_link;
    }
}

// 3. 解析查询变量
add_action( 'template_include', 'product_category_template' );

function product_category_template( $template ) {
    $product_category = get_query_var( 'product_category' );
    if ( is_singular( 'product' ) && ! empty( $product_category ) ) {
        // 这里可以根据 $product_category 的值来加载不同的模板
        // 例如，你可以创建一个名为 "single-product-category.php" 的模板
        $new_template = locate_template( array( 'single-product-category.php' ) );
        if ( ! empty( $new_template ) ) {
            return $new_template;
        }
    }
    return $template;
}

// 别忘了刷新固定链接结构，否则不会生效!

代码解释：

• add_product_category_query_var 函数注册了一个名为 product_category 的查询变量。
• custom_product_permalink_with_category 函数修改了 product 类型的永久链接，将 product_category 的值添加到永久链接中。
• product_category_template 函数根据 product_category 的值来加载不同的模板。

查询变量的优势：

• 更好的 SEO： 使用查询变量可以创建更具描述性的 URL，有利于 SEO。
• 更灵活的路由： 可以根据查询变量的值来加载不同的模板，实现更灵活的路由。
• 更强大的功能： 可以将查询变量与其他 WordPress 功能结合使用，实现更强大的功能。

总结：

post_type_link 过滤器是 WordPress 中一个非常强大的工具，可以用来修改自定义文章类型的永久链接。通过结合 rewrite 参数和查询变量，我们可以创建各种各样的永久链接结构，满足不同的需求。希望今天的讲座能帮助你更好地理解和使用 post_type_link 过滤器。记住，灵活运用这些工具，你的 WordPress 网站将会更加出色！

表格总结：

功能	rewrite 参数	post_type_link 过滤器	查询变量
作用	定义 CPT 的基本永久链接结构	动态修改永久链接	构建更复杂的永久链接结构，实现更灵活的路由
适用场景	全局性的、静态的永久链接规则	需要根据文章内容或其他条件动态生成永久链接的场景	需要更复杂的 URL 结构，例如分类、标签等
灵活性	较低	较高	最高
易用性	简单	较复杂	复杂
SEO 友好程度	良好	良好	更好
性能影响	较低	较高（如果逻辑复杂）	较高（需要解析查询变量）
是否需要刷新固定链接	是	是	是

好了，今天的讲座就到这里，希望大家有所收获！下次有机会再和大家分享更多 WordPress 开发的技巧。 拜拜！