本文深入探讨 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 的预期行为。
以下是使用输出缓冲的基本步骤：
- ob_start(): 在短代码函数开始时调用此函数，它会开启一个输出缓冲区。之后所有通过 echo、print 或直接 HTML 标签输出的内容都将被捕获到这个缓冲区中，而不会直接发送到浏览器。
- 内容生成: 在 ob_start() 和 ob_get_clean() 之间编写你的 HTML、PHP 逻辑等，所有输出都会被缓冲。
- ob_get_clean(): 在短代码函数结束时调用此函数。它会获取缓冲区中的所有内容，然后清空缓冲区并关闭它。最重要的是，它会返回缓冲区中的内容。
- return: 将 ob_get_clean() 返回的内容作为短代码函数的返回值。
示例代码：
<?php function my_custom_shortcode_function() { // 开启输出缓冲 ob_start(); // 在这里放置所有需要输出的HTML和PHP逻辑 // 例如，一个简单的表单 ?> <form method="POST"> <input type="text" name="filter" placeholder="输入关键词..."/> <input type="submit" value="搜索"/> </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"> <input type="text" name="filter" placeholder="输入职位关键词或ID..." /> <input type="submit" value="搜索职位" /> </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 规范的自定义短代码。
评论（已关闭）
评论已关闭