理解“无效 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 %%"。
完整的短代码实现示例
以下是一个改进后的短代码函数示例，它结合了输出缓冲、安全数据库查询和基本的错误处理：
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 '搜索表单加载失败。
'; // 或者直接返回错误信息
}
// 开启输出缓冲
ob_start();
?>
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) {
?>
列1
列2
列3
未找到匹配的结果。';
}
} else {
// 如果没有筛选条件，可以显示提示信息
echo '请输入搜索条件以查找信息。
';
}
?>
对应的 form.html 文件示例：
注意事项：
- 表名约定： 始终使用 $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 自定义短代码。
