WordPress自定义短代码在古腾堡编辑器中出现报错，通常和短代码的注册方式、古腾堡的解析逻辑、内容渲染流程不匹配有关，常见的报错场景包括短代码不生效、输出内容格式错乱、编辑器提示语法错误等。
常见报错原因分析
1. 短代码注册时机不正确
如果在 init 钩子之前就注册短代码，或者注册逻辑放在了错误的执行周期中，古腾堡编辑器在解析内容时可能无法识别短代码，导致报错。
2. 短代码输出包含未转义的特殊字符
短代码回调函数中如果直接输出包含 <、>、& 等未转义字符的内容，古腾堡编辑器在解析时会将其误认为是HTML标签，触发语法错误提示。
3. 短代码返回值格式不符合要求
古腾堡编辑器对短代码的返回值有格式要求，如果短代码返回了不完整的结构、或者直接输出了脚本、样式标签，也可能导致解析异常。
解决方案步骤
第一步：调整短代码注册时机
确保短代码在 init 钩子中注册，这是WordPress官方推荐的注册时机，能够保证古腾堡编辑器和前端都可以正确识别短代码。以下是正确注册的示例代码：
// 正确的短代码注册方式
add_action('init', 'register_custom_shortcode');
function register_custom_shortcode() {
// 注册短代码，第一个参数是短代码名称，第二个是回调函数
add_shortcode('my_custom_shortcode', 'my_custom_shortcode_callback');
}
// 短代码回调函数
function my_custom_shortcode_callback($atts) {
// 处理短代码属性
$atts = shortcode_atts(array(
'title' => '默认标题',
'content' => '默认内容'
), $atts);
// 返回处理后的内容，不要直接echo
return '<div class="custom-shortcode"><h3>' . esc_html($atts['title']) . '</h3><p>' . esc_html($atts['content']) . '</p></div>';
}
第二步：转义输出内容中的特殊字符
短代码回调函数返回的内容中，所有动态拼接的内容都需要使用 esc_html 或者 wp_kses 等函数转义，避免特殊字符被古腾堡编辑器误解析。如果确实需要输出HTML内容，可以使用 wp_kses_post 过滤允许的标签：
function my_custom_shortcode_callback($atts) {
$atts = shortcode_atts(array(
'content' => '默认内容'
), $atts);
// 允许输出安全的HTML内容，过滤掉危险标签
$allowed_html = array(
'strong' => array(),
'em' => array(),
'a' => array(
'href' => array(),
'title' => array()
)
);
return '<div class="custom-content">' . wp_kses($atts['content'], $allowed_html) . '</div>';
}
第三步：避免短代码直接输出脚本和样式
不要在短代码回调函数中直接输出 <script> 或者 <style> 标签，古腾堡编辑器不支持在内容区域直接解析这类标签。如果需要添加样式或者脚本，应该通过 wp_enqueue_scripts 钩子加载，或者使用 wp_add_inline_style 添加内联样式：
// 加载短代码所需的样式
add_action('wp_enqueue_scripts', 'enqueue_shortcode_styles');
function enqueue_shortcode_styles() {
// 注册样式文件
wp_register_style('custom-shortcode-style', get_template_directory_uri() . '/css/custom-shortcode.css');
// 如果需要内联样式，可以这样添加
$inline_style = '.custom-shortcode { padding: 10px; border: 1px solid #eee; }';
wp_add_inline_style('custom-shortcode-style', $inline_style);
}
// 短代码回调函数中只返回结构内容
function my_custom_shortcode_callback($atts) {
// 入队样式，确保前端加载
wp_enqueue_style('custom-shortcode-style');
return '<div class="custom-shortcode">短代码内容</div>';
}
第四步：排查古腾堡编辑器兼容性问题
如果以上步骤都检查后还是有报错，可以尝试暂时切换回经典编辑器，测试短代码是否正常工作。如果经典编辑器正常，说明是古腾堡的解析问题，可以尝试给短代码添加古腾堡块支持，将短代码封装成自定义块：
// 注册古腾堡块，包装自定义短代码
add_action('init', 'register_shortcode_block');
function register_shortcode_block() {
// 注册块类型
register_block_type('my-plugin/custom-shortcode-block', array(
'render_callback' => 'my_custom_shortcode_callback',
'attributes' => array(
'title' => array(
'type' => 'string',
'default' => '默认标题'
)
)
));
}
验证修复效果
完成以上修改后，清除WordPress的缓存和浏览器缓存，重新打开古腾堡编辑器，插入自定义短代码测试。如果短代码可以正常解析、输出内容格式正确，且没有报错提示，说明问题已经修复。
如果仍然存在问题，可以开启WordPress的调试模式，查看具体的报错信息，根据报错提示进一步调整代码逻辑。