WordPress自定义文章类型wp_link_pages分页失效问题求助

嘿，这个问题我之前在开发自定义文章类型时也踩过坑！wp_link_pages能生成分页链接但点击无反应，大概率是自定义文章类型（CPT）的配置没跟上，导致WordPress无法正确解析分页请求。下面是一步步的排查和解决方法：

1. 确认自定义文章类型注册时的分页重写配置 #

注册CPT时，必须在rewrite参数里明确开启分页支持，也就是添加'pages' => true。如果漏掉这个，WordPress不会为CPT生成对应的分页重写规则，点击链接自然没反应。

示例注册代码：

function register_my_custom_post_type() {
    $args = array(
        'labels' => array(
            'name' => __( '我的自定义文章' ),
            'singular_name' => __( '自定义文章' )
        ),
        'public' => true,
        'has_archive' => true,
        'rewrite' => array(
            'slug' => 'my-custom-post',
            'pages' => true, // 关键：启用分页重写规则
            'with_front' => false // 可选，根据你的固定链接结构调整
        ),
        'supports' => array( 'title', 'editor', 'thumbnail' ) // editor必须有，才能添加<!--nextpage-->标签
    );
    register_post_type( 'my_custom_post', $args );
}
add_action( 'init', 'register_my_custom_post_type' );

2. 刷新重写规则 #

修改CPT注册代码后，一定要去WordPress后台的设置 → 固定链接页面，直接点击「保存更改」（不需要修改任何设置）。这一步会让WordPress重新生成重写规则，新的分页规则才会生效——很多人就是漏掉这一步导致问题迟迟解决不了。

3. 检查wp_link_pages的调用位置和参数 #

确保你在自定义文章类型的模板文件（比如single-my_custom_post.php）中，正确在主循环内调用wp_link_pages()。比如：

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>
    <h1><?php the_title(); ?></h1>
    <?php the_content(); ?>
    <!-- 在这里调用分页链接 -->
    <?php wp_link_pages( array(
        'before' => '<div class="page-navigation">' . __( '分页：', 'your-theme-textdomain' ),
        'after'  => '</div>',
        'link_before' => '<span>',
        'link_after' => '</span>'
    ) ); ?>
<?php endwhile; endif; ?>

注意：必须在the_post()之后调用，这样才能获取当前文章的分页信息。

4. 排查查询变量被过滤的情况 #

少数情况下，主题或插件可能会修改query_vars，导致分页用的page参数被移除。如果前面的步骤都没用，可以试试在主题的functions.php中添加以下代码，确保page变量被保留：

function preserve_cpt_page_query_var( $query_vars ) {
    if ( ! in_array( 'page', $query_vars ) ) {
        $query_vars[] = 'page';
    }
    return $query_vars;
}
add_filter( 'query_vars', 'preserve_cpt_page_query_var' );

5. 检查固定链接结构 #

避免使用「朴素」固定链接（即?p=123这种格式），推荐使用「文章名」或自定义结构的固定链接。因为wp_link_pages生成的分页链接依赖于漂亮的permalink结构，朴素模式下分页参数可能无法被CPT正确识别。

总结 #

最常见的问题就是注册CPT时没开启pages重写，加上忘记刷新重写规则。先把这两步做了，90%的情况都能解决。如果还是不行，再依次排查后面的步骤。

内容的提问来源于stack exchange，提问作者Asad