理解“无效 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() 返回的内容作为短代码函数的返回值。
示例代码：
增强安全性：使用 $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 模式中使用 % 作为通配符时，需要将其双重转义为 %%。
示例：安全的数据库查询
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 ) ) {
?>
| 列1 | 列2 | 列3 |
|---|---|---|
抱歉，没有找到匹配的结果。
注意事项：
- 表名安全： $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）攻击。
完整代码示例（整合优化）
结合上述所有最佳实践，以下是一个更健壮、安全的短代码实现：
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 '错误：搜索表单文件未找到。
';
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)) {
?>
| 职位名称 | 地点 | 发布日期 |
|---|---|---|
抱歉，没有找到匹配您搜索条件的结果。
form.html 内容示例：
总结
解决 WordPress 短代码中“无效 JSON 响应”错误的核心在于遵循 WordPress 的短代码处理机制：短代码函数必须返回其内容，而不是直接输出。通过使用 PHP 的输出缓冲 (ob_start() 和 ob_get_clean())，可以有效地管理短代码的输出。
此外，在处理数据库交互时，务必采纳安全最佳实践：
- 使用 $wpdb->prepare() 来防止 SQL 注入。
- 正确转义 SQL LIKE 通配符 (% 应双重转义为 %%)。
- 对所有用户输入进行清理 (sanitize_text_field() 等)。
- 对所有输出到 HTML 的内容进行转义 (esc_html()、esc_url() 等)，以防止 XSS 攻击。
遵循这些原则，将有助于您开发出更安全、稳定且符合 WordPress 规范的自定义短代码。
