WordPress 自定义文章类型 QA 完整路由方案：支持分类、分页与文章详情的最优实现

2025-12-10
5:21 下午
高级教程

在企业知识库、FAQ 系统或技术问答中心的开发中，自定义文章类型（Custom Post Type, CPT）与自定义分类法（Custom Taxonomy）是最常用的工具。本文将以实际项目为例，讲述如何利用 CPT UI 插件创建一个名为 qa 的自定义文章类型，并配合自定义分类法 qa-cat 构建如下访问结构：

/qa/
/qa/page/2/
/qa/{分类slug}/
/qa/{分类slug}/page/2/
/qa/{文章slug}/

同时本文将完整解决一个常见问题：
访问文章详情页出现 404 的冲突问题。

内容包含完整代码、路由逻辑解释，以及如何让 WordPress 正确区分“文章 slug”和“分类 slug”。

一、项目需求背景

本文的实际需求场景如下：

使用 CPT UI 创建自定义文章类型：
- 名称：qa
- 访问 slug：qa
使用 CPT UI 创建自定义分类法：
- 名称：qa-cat
- 作用于文章类型：qa
创建一个页面（Page）：
- 页面名：QA
- 页面 slug：qa
实现统一的访问结构：

类型示例 URL

QA 主页面 /qa/

QA 主页面分页 /qa/page/2/

分类归档 /qa/anquanyinsi/

分类分页 /qa/anquanyinsi/page/2/

QA 文章详情 /qa/telegramdejiami…/
要求优先匹配文章详情页；如果不是文章，则匹配分类；如果都不是，则显示 404。

类型	示例 URL
QA 主页面	/qa/
QA 主页面分页	/qa/page/2/
分类归档	/qa/anquanyinsi/
分类分页	/qa/anquanyinsi/page/2/
QA 文章详情	/qa/telegramdejiami…/

在实际开发中，如果仅依赖标准 CPT UI 或默认 rewrite 规则，通常会遇到严重冲突，例如：

分类 slug 与文章 slug 同级，默认 rewrite 无法区分
页面 slug 又与自定义文章类型 slug 相同（/qa/），路由层面冲突更明显
文章详情经常出现 404
/qa/page/2/ 或 /qa/{term}/page/2/ 也会出现 404

因此，需要一套完整的 rewrite + 动态解析方案。

二、基础 rewrite 规则构建：实现 QA 的路由结构

以下代码实现固定路由规则，包括 QA 主页面、分页、分类、分类分页以及文章详情页：

add_filter('query_vars', function ($vars) {
    $vars[] = 'qa-cat';
    return $vars;
});

add_action('init', function () {

    // 文章详情页规则
    add_rewrite_rule(
        '^qa/([^/]+)/?$',
        'index.php?post_type=qa&name=$matches[1]',
        'top'
    );

    // 分类分页
    add_rewrite_rule(
        '^qa/([^/]+)/page/([0-9]{1,})/?$',
        'index.php?pagename=qa&qa-cat=$matches[1]&paged=$matches[2]',
        'top'
    );

    // 分类基础
    add_rewrite_rule(
        '^qa/([^/]+)/?$',
        'index.php?pagename=qa&qa-cat=$matches[1]',
        'top'
    );

    // QA 页面分页
    add_rewrite_rule(
        '^qa/page/([0-9]{1,})/?$',
        'index.php?pagename=qa&paged=$matches[1]',
        'top'
    );
});

为什么文章详情规则要放最前面？

rewrite 系统会自上而下匹配。
如果文章详情不放在最上面，分类规则会截获文章 slug，导致文章详情无法访问。

三、文章详情 404 的根本原因

即使按照最佳顺序排列规则，仍然会遇到一个典型问题：

访问文章详情页：

/qa/telegramdejiamitongxungongnengjutishizhishenmeshifouzugouanquankekao/

结果仍然是 404。

原因是：

WordPress 无法判断 slug 是：

文章 slug（post_name）
分类 slug（taxonomy term）

因此无论你如何写 rewrite，只要 slug 重名或者规则相似，官方的路由机制就会出现歧义。

要解决这个问题，必须在 parse_request 阶段进行动态判断。

四、最终方案：动态判断 slug 类型（文章优先）

以下代码是解决文章详情 404 的核心：

add_action('parse_request', function ($wp) {

    if (!isset($wp->query_vars['pagename']) || $wp->query_vars['pagename'] !== 'qa') {
        return;
    }

    $slug = $wp->query_vars['qa-cat'] ?? null;

    if (!$slug) {
        return;
    }

    // 第一优先：文章
    $post = get_page_by_path($slug, OBJECT, 'qa');
    if ($post) {
        $wp->query_vars = [
            'post_type' => 'qa',
            'name'      => $slug,
        ];
        return;
    }

    // 第二优先：分类
    $term = get_term_by('slug', $slug, 'qa-cat');
    if ($term) {
        return;
    }

    // 第三：不存在
    $wp->query_vars = ['error' => '404'];
});

该逻辑的优先级顺序：

如果 slug 是 qa 文章 → 显示文章详情
如果 slug 是 qa-cat 分类 → 显示分类页面
否则 → 返回 404

这一逻辑使得路由系统完全可靠。

五、QA 页面模板强制切换

为了保证分类列表与 QA 主页面使用同一个模板，可以添加：

add_filter('template_include', function ($template) {
    if (is_page('qa')) {
        $t = locate_template('page-qa.php');
        if ($t) return $t;
    }
    return $template;
});