WordPress短代码JSON错误解决方法

欢迎各位小伙伴来到golang学习网，相聚于此都是缘哈哈哈！今天我给大家带来《WordPress 短代码JSON错误排查指南》，这篇文章主要讲到等等知识，如果你对文章相关的知识非常感兴趣或者正在自学，都可以关注我，我会持续更新相关文章！当然，有什么建议也欢迎在评论留言提出！一起学习！

本文深入探讨 WordPress 自定义短代码中“无效 JSON 响应”错误的常见原因，并提供一套全面的解决方案。核心在于理解短代码应“返回”内容而非“输出”内容，通过使用 PHP 输出缓冲机制（ob_start() 和 ob_get_clean()）来捕获并返回 HTML。同时，文章强调了数据库操作的安全性，详细讲解了如何使用 $wpdb->prepare() 防止 SQL 注入，并给出了处理 SQL LIKE 通配符的正确方法，旨在帮助开发者编写更健壮、安全的 WordPress 短代码。

理解“无效 JSON 响应”错误

在 WordPress 开发中，尤其是涉及到自定义短代码时，开发者可能会遇到“无效 JSON 响应”错误。这个错误通常发生在尝试保存或更新包含特定短代码的内容时，例如在使用古腾堡编辑器或经典编辑器时。其根本原因在于 WordPress 期望短代码函数能够返回其生成的 HTML 内容，而不是直接使用 echo 或 print 进行输出。

当 WordPress 后台通过 AJAX 请求与服务器通信时（例如保存文章内容），它期望服务器返回一个格式良好的 JSON 响应。如果短代码在执行过程中直接输出了任何内容（例如 HTML、文本、甚至空白字符），这些内容会混入到 WordPress 预期的 JSON 响应之前或之中，从而破坏 JSON 结构，导致客户端解析失败，并报告“无效 JSON 响应”错误。

另一个常见但容易被忽视的问题是，短代码函数中不应使用 exit() 或 die()。这些函数会立即终止 PHP 脚本的执行，这不仅会阻止短代码返回内容，还会中断整个 WordPress 请求的处理流程，导致不可预测的行为或错误。

解决方案：使用输出缓冲机制

解决此问题的关键在于使用 PHP 的输出缓冲（Output Buffering）机制。通过将所有需要输出的内容捕获到一个缓冲区中，并在短代码函数结束时将缓冲区的内容作为函数返回值，可以确保短代码符合 WordPress 的预期行为。

以下是使用输出缓冲的基本步骤：

1. ob_start(): 在短代码函数开始时调用此函数，它会开启一个输出缓冲区。之后所有通过 echo、print 或直接 HTML 标签输出的内容都将被捕获到这个缓冲区中，而不会直接发送到浏览器。
2. 内容生成: 在 ob_start() 和 ob_get_clean() 之间编写你的 HTML、PHP 逻辑等，所有输出都会被缓冲。
3. ob_get_clean(): 在短代码函数结束时调用此函数。它会获取缓冲区中的所有内容，然后清空缓冲区并关闭它。最重要的是，它会返回缓冲区中的内容。
4. return: 将 ob_get_clean() 返回的内容作为短代码函数的返回值。

示例代码：

<?php
function my_custom_shortcode_function() {
    // 开启输出缓冲
    ob_start();

    // 在这里放置所有需要输出的HTML和PHP逻辑
    // 例如，一个简单的表单
    ?>
    <form method="POST">
        &lt;input type=&quot;text&quot; name=&quot;filter&quot; placeholder=&quot;输入关键词...&quot;/&gt;
        &lt;input type=&quot;submit&quot; value=&quot;搜索&quot;/&gt;
    </form>
    <?php

    // 获取缓冲区内容并返回
    return ob_get_clean();
}
add_shortcode('my_custom_shortcode', 'my_custom_shortcode_function');
?>

增强安全性：使用 $wpdb->prepare()

在处理数据库查询时，安全性是至关重要的。直接将用户输入（如 $_POST 或 $_GET 数据）拼接到 SQL 查询字符串中，会使你的网站面临 SQL 注入攻击的风险。WordPress 提供了 $wpdb->prepare() 方法来安全地构建 SQL 查询。

$wpdb->prepare() 的工作方式类似于 sprintf()，它会根据提供的格式字符串和参数来构建一个安全的 SQL 查询。

基本用法：

$wpdb->prepare( $format, $arg1, $arg2, ... )

• %s：用于字符串（会自动添加引号）。
• %d：用于整数。
• %f：用于浮点数。

处理 SQL LIKE 通配符 (%)：

在使用 LIKE 子句时，% 符号既是 SQL 的通配符，也可能被 prepare 函数误认为是格式占位符。为了避免混淆，当在 LIKE 模式中使用 % 作为通配符时，需要将其双重转义为 %%。

示例：安全的数据库查询

<?php
function my_secure_shortcode_function() {
    global $wpdb;
    ob_start();

    $table_name = $wpdb->prefix . 'my_custom_table'; // 推荐使用 $wpdb->prefix 获取表前缀
    $filter = isset($_POST['filter']) ? sanitize_text_field($_POST['filter']) : ''; // 始终对用户输入进行清理

    // 假设 form.html 包含搜索表单
    require_once( WP_PLUGIN_DIR . '/your-plugin-dir/assets/runtime/shortcode/form.html' );

    // 构建安全的查询
    // 注意：这里的 %s 占位符是用于 $table_name 的，因为表名不能直接通过 prepare 转义
    // 但在实际中，表名通常是固定的，或者通过白名单验证，而不是用户输入
    // 对于 LIKE 模式中的 %，需要使用 %% 进行双重转义
    $query = $wpdb->prepare(
        "SELECT id, column1, column2, column3 FROM {$table_name} WHERE column1 LIKE %s OR id LIKE %s",
        '%' . $wpdb->esc_like($filter) . '%', // 使用 $wpdb->esc_like() 转义 LIKE 模式中的特殊字符
        '%' . $wpdb->esc_like($filter) . '%'
    );

    $results = $wpdb->get_results( $query, ARRAY_A );

    if ( ! empty( $results ) ) {
        ?>
        <table>
            <tr>
                <th>列1</th>
                <th>列2</th>
                <th>列3</th>
            </tr>
            <?php foreach ( $results as $row ) : ?>
                <tr>
                    <td><a href="<?php echo esc_url(site_url('/displayjobs?id=' . $row['id'])); ?>"><?php echo esc_html($row['column1']); ?></a></td>
                    <td><?php echo esc_html($row['column2']); ?></td>
                    <td><?php echo esc_html($row['column3']); ?></td>
                </tr>
            <?php endforeach; ?>
        </table>
        <?php
    } else {
        ?>
        <p>抱歉，没有找到匹配的结果。</p>
        <?php
    }

    return ob_get_clean();
}
add_shortcode('my_secure_shortcode', 'my_secure_shortcode_function');
?>

注意事项：

• 表名安全： $wpdb->prepare() 不会为表名添加引号或转义。因此，表名应始终通过硬编码、白名单验证或 sprintf 格式化后安全地插入查询，而不是直接来自用户输入。在上述示例中，{$table_name} 是直接插入的，因为 $table_name 是在代码内部定义的，而非用户输入。
• $wpdb->esc_like()： 当你希望用户输入中的 _ 或 % 被视为字面字符而不是通配符时，应该使用 $wpdb->esc_like() 来转义这些字符。然后，在 $wpdb->prepare() 中，将 % 通配符自身双重转义为 %%。
• 输入清理： 在将用户输入用于任何目的之前，始终使用 WordPress 提供的清理函数（如 sanitize_text_field()、absint() 等）进行清理。
• 输出转义： 在将任何动态内容输出到 HTML 中时，始终使用 esc_html()、esc_attr()、esc_url() 等函数进行转义，以防止跨站脚本（XSS）攻击。

完整代码示例（整合优化）

结合上述所有最佳实践，以下是一个更健壮、安全的短代码实现：

<?php
/**
 * 注册自定义短代码 'my_job_search'
 */
function register_my_job_search_shortcode() {
    add_shortcode('my_job_search', 'my_job_search_shortcode_callback');
}
add_action('init', 'register_my_job_search_shortcode');

/**
 * 自定义工作搜索短代码回调函数
 *
 * @return string 生成的HTML内容
 */
function my_job_search_shortcode_callback() {
    global $wpdb;
    ob_start(); // 开启输出缓冲

    // 定义表名，推荐使用 $wpdb->prefix
    $job_table_name = $wpdb->prefix . 'jobs'; // 假设你的表名为 wp_jobs

    // 获取并清理用户输入
    $filter = isset($_POST['filter']) ? sanitize_text_field($_POST['filter']) : '';

    // 引入搜索表单 HTML
    // 确保路径正确，并使用 require_once 以避免重复引入
    $form_path = WP_PLUGIN_DIR . '/your-plugin-directory/assets/runtime/shortcode/form.html';
    if (file_exists($form_path)) {
        require_once($form_path);
    } else {
        echo '<p>错误：搜索表单文件未找到。</p>';
        return ob_get_clean(); // 提前返回错误信息
    }

    // 如果没有筛选条件，或者表为空，则不执行查询，直接返回表单
    // 检查表是否有条目，但更推荐直接查询，如果结果为空则显示“无结果”
    // if ( $wpdb->get_var( "SELECT COUNT(*) FROM {$job_table_name}" ) == 0 && empty($filter) ) {
    //     // 表单已输出，直接返回
    //     return ob_get_clean();
    // }

    $results = [];
    if (!empty($filter)) {
        // 构建安全的SQL查询
        // 使用 $wpdb->prepare() 防止 SQL 注入
        // 对于 LIKE 中的 % 通配符，使用 %% 进行双重转义
        // 使用 $wpdb->esc_like() 转义用户输入中可能存在的 LIKE 特殊字符
        $query = $wpdb->prepare(
            "SELECT id, column1, column2, column3 FROM {$job_table_name} WHERE column1 LIKE %s OR id LIKE %s",
            '%' . $wpdb->esc_like($filter) . '%',
            '%' . $wpdb->esc_like($filter) . '%'
        );
        $results = $wpdb->get_results($query, ARRAY_A);
    }

    // 显示结果
    if (!empty($results)) {
        ?>
        <table>
            <thead>
                <tr>
                    <th>职位名称</th>
                    <th>地点</th>
                    <th>发布日期</th>
                </tr>
            </thead>
            <tbody>
                <?php foreach ($results as $result) : ?>
                    <tr>
                        <td>
                            <a href="<?php echo esc_url(site_url('/displayjobs?id=' . $result['id'])); ?>">
                                <?php echo esc_html($result['column1']); ?>
                            </a>
                        </td>
                        <td><?php echo esc_html($result['column2']); ?></td>
                        <td><?php echo esc_html($result['column3']); ?></td>
                    </tr>
                <?php endforeach; ?>
            </tbody>
        </table>
        <?php
    } elseif (!empty($filter)) {
        // 只有当有筛选条件但没有结果时才显示此消息
        ?>
        <p>抱歉，没有找到匹配您搜索条件的结果。</p>
        <?php
    }

    return ob_get_clean(); // 获取缓冲区内容并返回
}
?>

form.html 内容示例：

<form method="POST">
  &lt;input type=&quot;text&quot; name=&quot;filter&quot; placeholder=&quot;输入职位关键词或ID...&quot; /&gt;
  &lt;input type=&quot;submit&quot; value=&quot;搜索职位&quot; /&gt;
</form>

总结

解决 WordPress 短代码中“无效 JSON 响应”错误的核心在于遵循 WordPress 的短代码处理机制：短代码函数必须返回其内容，而不是直接输出。通过使用 PHP 的输出缓冲 (ob_start() 和 ob_get_clean())，可以有效地管理短代码的输出。

此外，在处理数据库交互时，务必采纳安全最佳实践：

• 使用 $wpdb->prepare() 来防止 SQL 注入。
• 正确转义 SQL LIKE 通配符 (% 应双重转义为 %%)。
• 对所有用户输入进行清理 (sanitize_text_field() 等)。
• 对所有输出到 HTML 的内容进行转义 (esc_html()、esc_url() 等)，以防止 XSS 攻击。

遵循这些原则，将有助于您开发出更安全、稳定且符合 WordPress 规范的自定义短代码。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。