本教程旨在解决WordPress插件开发中，自定义查询变量（`query_vars`）在模板中无法通过 `get_query_var` 获取的问题。文章将详细阐述如何正确地注册自定义查询变量、添加重写规则，并纠正常见的模板加载错误，即在 `parse_request` 钩子中过早使用 `require` 和 `exit()`，从而确保 `get_query_var` 能够正常工作。

在WordPress插件开发中，为自定义功能定义特定的URL结构、处理查询变量并加载对应的模板是常见的需求。然而，开发者有时会遇到一个困扰：即使自定义的URL成功加载了指定的模板，但在模板内部使用 get_query_var() 函数尝试获取自定义查询变量时，却始终返回空值。这通常是由于对WordPress请求生命周期的理解不足，尤其是在处理模板加载方式上。

1. 正确注册自定义查询变量

首先，为了让WordPress识别并处理自定义的URL查询变量，我们需要将其添加到允许的查询变量列表中。这通过 query_vars 过滤器实现。

add_filter('query_vars', function ($query_vars) {
    $query_vars[] = 'wps_service_id'; // 添加你的自定义查询变量名
    return $query_vars;
});

这段代码将 wps_service_id 添加到WordPress的公共查询变量数组中，使其能够被WordPress的查询处理器识别。

2. 定义自定义重写规则

接下来，我们需要定义一个重写规则，将自定义的URL结构映射到内部的WordPress查询参数。这通常在 init 动作钩子中完成，使用 add_rewrite_rule() 函数。

add_action('init', function () {
    add_rewrite_rule(
        'services/([a-z0-9-]+)/?$', // 匹配的URL模式
        'index.php?wps_service_id=$matches[1]', // 内部重写目标
        'top' // 规则优先级，'top'表示最高优先级
    );
});

此规则会将形如 /services/your-service-slug/ 的URL重写为 index.php?wps_service_id=your-service-slug。

重要提示：刷新重写规则

在添加或修改重写规则后，WordPress需要刷新其内部的重写规则缓存才能使新规则生效。最简单的方法是访问WordPress后台的“设置” -> “固定链接”页面。在插件开发中，你可以在插件激活时调用 flush_rewrite_rules()，并在插件停用时再次调用以清除规则。

// 插件激活时
register_activation_hook(__FILE__, 'my_plugin_activate');
function my_plugin_activate() {
    // 确保在init钩子之后执行，以包含你的规则
    my_plugin_add_rewrite_rules(); // 你的add_rewrite_rule函数
    flush_rewrite_rules();
}

// 插件停用时
register_deactivation_hook(__FILE__, 'my_plugin_deactivate');
function my_plugin_deactivate() {
    flush_rewrite_rules();
}

// 确保在init钩子中调用 add_rewrite_rule
add_action('init', 'my_plugin_add_rewrite_rules');
function my_plugin_add_rewrite_rules() {
    add_rewrite_rule(
        'services/([a-z0-9-]+)/?$',
        'index.php?wps_service_id=$matches[1]',
        'top'
    );
}

3. 常见的错误：在 parse_request 中过早终止请求

许多开发者在 parse_request 钩子中检查自定义查询变量，并直接使用 require 语句加载模板，然后调用 exit()。

// 错误的模板加载方式
add_action('parse_request', function (&$wp) {
    if (array_key_exists('wps_service_id', $wp->query_vars)) {
        require plugin_dir_path(__DIR__) . "views/service.php";
        exit(); // 问题所在！
    }
    return;
});

尽管这种方法能够成功加载模板，但它会导致 get_query_var() 在模板中无法获取到值。根本原因在于 exit() 函数过早地终止了WordPress的执行流程。 get_query_var() 函数依赖于 $wp_query 全局对象，而 $wp_query 只有在WordPress完成其主查询（即 WP::main() 方法执行完毕）之后才会被完全填充。在 parse_request 阶段 exit() 会阻止这一关键步骤的完成。

4. 正确的模板加载方式：使用 template_include 过滤器

为了在加载自定义模板的同时，确保WordPress的查询变量处理流程完整执行，我们应该使用 template_include 过滤器。这个过滤器允许你在WordPress决定加载哪个模板文件之后，但在实际加载之前，介入并指定一个不同的模板文件。

// 正确的模板加载方式
add_filter('template_include', function ($template) {
    // 获取自定义查询变量
    $service_id = get_query_var('wps_service_id');

    // 如果自定义查询变量存在且非空
    if (!empty($service_id)) {
        // 定义你的自定义模板文件路径
        $plugin_template = plugin_dir_path(__DIR__) . "views/service.php";

        // 检查模板文件是否存在
        if (file_exists($plugin_template)) {
            return $plugin_template; // 返回自定义模板路径
        }
    }
    return $template; // 如果不符合条件，返回WordPress默认的模板
});

通过这种方式，WordPress会先完成所有查询变量的处理，填充 $wp_query 对象，然后才到达 template_include 过滤器。此时，get_query_var() 就能正常地从 $wp_query 中检索到 wps_service_id 的值。

完整的正确实现示例

将上述所有正确的部分整合起来，一个功能完整的自定义查询变量和模板加载方案如下：

r Name
 */

// 1. 注册自定义查询变量
add_filter('query_vars', function ($query_vars) {
    $query_vars[] = 'wps_service_id';
    return $query_vars;
});

// 2. 定义自定义重写规则
add_action('init', 'my_plugin_add_rewrite_rules');
function my_plugin_add_rewrite_rules() {
    add_rewrite_rule(
        'services/([a-z0-9-]+)/?$',
        'index.php?wps_service_id=$matches[1]',
        'top'
    );
}

// 插件激活时刷新重写规则
register_activation_hook(__FILE__, 'my_plugin_activate');
function my_plugin_activate() {
    my_plugin_add_rewrite_rules(); // 确保规则已添加
    flush_rewrite_rules();
}

// 插件停用时刷新重写规则
register_deactivation_hook(__FILE__, 'my_plugin_deactivate');
function my_plugin_deactivate() {
    flush_rewrite_rules();
}

// 3. 使用 template_include 过滤器加载自定义模板
add_filter('template_include', function ($template) {
    $service_id = get_query_var('wps_service_id');

    if (!empty($service_id)) {
        // 确保路径正确，这里假设模板在插件根目录下的 'views' 文件夹中
        $plugin_template = plugin_dir_path(__FILE__) . "views/service.php"; 

        if (file_exists($plugin_template)) {
            return $plugin_template;
        }
    }
    return $template;
});

// 示例：views/service.php 模板文件内容
/*



    

        
Service Details for: 
        
This is a custom service page loaded by the plugin.
        
    



*/

注意事项与总结

• 路径准确性： 确保 plugin_dir_path(__FILE__) 或 plugin_dir_path(__DIR__) 正确指向你的模板文件所在目录。__FILE__ 指向当前文件，__DIR__ 指向当前文件所在的目录。
• 安全性： 从 get_query_var() 获取到的值应始终进行适当的清理和验证，尤其是在将其用于数据库查询或直接输出到HTML中时，以防止XSS或SQL注入攻击。例如，使用 esc_html() 进行HTML输出，使用 sanitize_text_field() 进行通用文本清理。
• 性能考量： 避免在每个请求上都调用 flush_rewrite_rules()。它是一个资源密集型操作，只应在插件激活/停用或重写规则真正改变时调用。
• 调试： 如果遇到问题，可以使用 error_log() 或 var_dump() 检查 $wp->query_vars 或 get_query_var() 的返回值，帮助定位问题。

通过遵循本教程中介绍的正确方法，你将能够有效地在WordPress插件中实现自定义URL、查询变量和模板加载，并确保 get_query_var() 函数能够按预期工作，从而构建出更加健壮和专业的WordPress解决方案。