本文旨在解决 WordPress 自定义短代码在保存页面时引发“无效 JSON 响应”错误的问题。核心在于理解短代码函数必须返回内容而非直接输出（echo），并结合输出缓冲技术（ob_start, ob_get_clean）来正确处理。同时，强调使用 $wpdb->prepare 进行数据库查询以防范 SQL 注入，并提供完整的代码示例和开发最佳实践，确保短代码的健壮性、安全性和兼容性。
理解“无效 JSON 响应”错误
当你在 wordpress 编辑器中插入自定义短代码并尝试更新或保存页面时，如果遇到“无效 json 响应”错误，这通常意味着 wordpress 后台的 ajax 请求未能收到预期的 json 格式响应。对于短代码而言，一个常见的误区是直接在短代码函数中使用 echo 输出内容。
WordPress 短代码的约定是：短代码函数应该返回它希望显示的内容，而不是直接将其输出到浏览器。当你在短代码函数中直接使用 echo 时，这些内容会在 WordPress 尝试发送其预期的 JSON 响应之前被输出。这会导致 JSON 响应被“污染”，从而引发“无效 JSON 响应”错误。尤其是在 Gutenberg 编辑器或任何依赖 AJAX 保存的场景下，这个问题会更加突出。
解决方案：输出缓冲（Output Buffering）
解决此问题的关键在于使用 PHP 的输出缓冲机制。通过 ob_start() 和 ob_get_clean() 函数，我们可以捕获短代码函数中所有 echo 的内容，然后将其作为字符串返回，从而符合 WordPress 短代码的预期行为。
基本原理：
- ob_start()：开启输出缓冲，此后所有本应直接输出到浏览器的数据都会被捕获到缓冲区中。
- 短代码逻辑：在 ob_start() 和 ob_get_clean() 之间，你可以自由地使用 echo 或嵌入 HTML。
- ob_get_clean()：获取缓冲区中的所有内容，并清空缓冲区，然后将捕获到的内容作为字符串返回。
增强安全性：使用 $wpdb->prepare()
除了解决“无效 JSON 响应”问题，开发自定义短代码时，与数据库的交互安全性至关重要。直接将用户输入（如 $_POST 或 $_GET）拼接到 SQL 查询字符串中是极其危险的，这会使你的网站面临 SQL 注入攻击的风险。
WordPress 提供了 $wpdb->prepare() 方法来安全地构建 SQL 查询。它类似于 sprintf()，可以防止 SQL 注入。
$wpdb->prepare() 的用法：
- 第一个参数是包含占位符的 SQL 查询字符串。
- 后续参数是与占位符对应的值。
- 占位符类型：
- %s：字符串
- %d：整数
- %f：浮点数
- 对于 SQL LIKE 子句中的 % 通配符，如果它们是字符串字面量的一部分，需要双重转义为 %%。例如，LIKE “%% %s %%”。
完整的短代码实现示例
以下是一个改进后的短代码函数示例，它结合了输出缓冲、安全数据库查询和基本的错误处理：
<?php /** * 注册自定义短代码 * [my_custom_search_form] */ function register_my_custom_shortcode() { add_shortcode('my_custom_search_form', 'my_custom_search_form_function'); } add_action('init', 'register_my_custom_shortcode'); /** * 自定义短代码函数：显示搜索表单并根据查询结果显示表格 */ function my_custom_search_form_function() { global $wpdb; // 定义数据库表名，建议使用 $wpdb->prefix 获取带前缀的表名 $table_name = $wpdb->prefix . 'your_custom_job_table'; // 替换为你的实际表名 // 获取并清理用户输入的筛选条件 $filter = isset($_POST['filter']) ? sanitize_text_field($_POST['filter']) : ''; // 引入搜索表单 HTML，通常放在插件目录的某个文件中 // 确保 form.html 存在于指定路径 $form_path = WP_PLUGIN_DIR . '/your_plugin_directory/assets/runtime/shortcode/form.html'; if (file_exists($form_path)) { require_once($form_path); } else { // 如果表单文件不存在，可以输出一个错误信息或默认内容 error_log('Shortcode form file not found: ' . $form_path); // return '<p>搜索表单加载失败。</p>'; // 或者直接返回错误信息 } // 开启输出缓冲 ob_start(); ?> <div class="my-custom-shortcode-wrapper"> <?php // 只有当有筛选条件时才执行数据库查询并显示结果 if (!empty($filter)) { // 构建查询：使用 $wpdb->prepare 防止 SQL 注入 // 注意 LIKE 子句中的 %% 用于转义 % $query = $wpdb->prepare( "SELECT id, column1, column2, column3 FROM %i WHERE column1 LIKE %s OR id LIKE %s", $table_name, '%' . $wpdb->esc_like($filter) . '%', // 使用 $wpdb->esc_like 处理通配符 '%' . $wpdb->esc_like($filter) . '%' ); $results = $wpdb->get_results($query, ARRAY_A); if ($results && count($results) > 0) { ?> <table> <thead> <tr> <th>列1</th> <th>列2</th> <th>列3</th> </tr> </thead> <tbody> <?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; ?> </tbody> </table> <?php } else { echo '<p>未找到匹配的结果。</p>'; } } else { // 如果没有筛选条件，可以显示提示信息 echo '<p>请输入搜索条件以查找信息。</p>'; } ?> </div> <?php // 获取缓冲区内容并返回 return ob_get_clean(); } ?>
对应的 form.html 文件示例：
<form method="POST" class="my-custom-search-form"> <input type="text" name="filter" placeholder="请输入搜索关键词..." value="<?php echo isset($_POST['filter']) ? esc_attr(sanitize_text_field($_POST['filter'])) : ''; ?>"/> <input type="submit" value="搜索"/> </form>
注意事项：
- 表名约定： 始终使用 $wpdb->prefix . ‘your_table_name’ 来获取正确的表名，以适应不同的 WordPress 安装。
- 输入清理： 在处理用户输入（如 $_POST[‘filter’]）时，务必使用 sanitize_text_field() 等 WordPress 提供的清理函数，以防止 XSS 攻击。
- 输出转义： 在将数据输出到 HTML 中时，使用 esc_html()、esc_attr()、esc_url() 等函数进行转义，防止 XSS 攻击。
- $wpdb->esc_like()： 在使用 LIKE 子句构建查询时，如果筛选条件本身可能包含 % 或 _，使用 $wpdb->esc_like() 来转义这些特殊字符，确保它们被视为字面量而不是通配符。
- 错误处理： 添加逻辑来处理查询无结果或文件不存在等情况，提升用户体验。
- 短代码注册： 确保你的短代码函数通过 add_shortcode() 正确注册，通常放在 init 动作钩子中。
总结
通过遵循以下核心原则，可以有效避免 WordPress 短代码中的“无效 JSON 响应”问题，并提升代码质量和安全性：
- 返回而非输出： 短代码函数必须返回其内容，而不是直接 echo。使用 ob_start() 和 ob_get_clean() 是实现此目的的标准方法。
- 安全性优先： 任何与数据库的交互都应使用 $wpdb->prepare() 来防止 SQL 注入。同时，对所有用户输入进行清理和输出进行转义。
- 结构清晰： 将 HTML 结构与 PHP 逻辑适当分离，例如通过 require 引入 HTML 模板文件，可以提高代码的可读性和可维护性。
- 错误处理： 考虑各种异常情况（如无结果、文件缺失）并提供友好的反馈。
遵循这些最佳实践，你将能够构建出健壮、安全且兼容性良好的 WordPress 自定义短代码。
评论（已关闭）
评论已关闭