使用REST API更新WordPress页面内容致Astra模板样式错乱

问题背景 #

我搭建了带Astra Starter Templates插件的WordPress站点，用REST API更新页面时出了问题：

• 操作步骤：先通过GET wp-json/wp/v2/pages/<id>拿到页面内容，只把<h1>里的“Hello World”改成“Hello People”，再把修改后的HTML作为content参数通过POST wp-json/wp/v2/pages/<id>提交
• 异常结果：更新后页面布局和样式全乱了，看源码发现WordPress要么加了随机标签，要么删了原有元素（比如<link>标签直接没了）
• 补充信息：站点用的是基于Spectra Blocks的Astra模板，生成的HTML不遵循Gutenberg的注释格式，调用wp-json/wp/v2/blocks接口返回空列表

截图对比 #

• 更新后返回内容 vs 提交的内容：
  
  
• 更新前后完整HTML对比（左侧是更新前，右侧是更新后，能看到<link>标签被移除）：
  

问题原因 #

WordPress REST API处理页面内容时，会触发内置的内容过滤与块解析机制：

1. 因为页面HTML是Spectra Blocks生成的，没有Gutenberg块特有的注释标记（比如<!-- wp:paragraph -->），WordPress无法识别为合法的块内容，会把整个HTML当作普通文本处理
2. 安全过滤功能（比如wp_filter_post_kses）会自动移除它判定为“不安全”的标签（像<link>这类外部资源引用标签常被过滤），同时对HTML做规范化调整（补全闭合标签、修正嵌套结构），直接破坏了原有布局的结构

解决方法 #

方案一：精准修改块内容（推荐） #

虽然wp-json/wp/v2/blocks返回空，但可以从原始内容里定位目标块修改：

• 从GET请求返回的content.raw字段中，找到包含目标<h1>的Spectra块片段（通常带有data-id、data-block这类自定义属性）
• 只修改该片段里的<h1>文本，完全保留块的原有结构和属性
• 将修改后的完整content.raw作为参数提交POST请求

方案二：针对性禁用内容过滤（谨慎使用） #

通过自定义代码允许Spectra Blocks所需的标签，绕过不必要的过滤：
在主题的functions.php或自定义插件中添加以下代码：

// 允许Spectra Blocks需要的HTML标签和属性
add_filter('wp_kses_allowed_html', function($allowed, $context) {
    if ($context === 'post') {
        // 放行<link>标签及常用属性
        $allowed['link'] = array(
            'rel' => true,
            'href' => true,
            'type' => true
        );
        // 放行div的自定义属性（适配Spectra Blocks）
        $allowed['div'] = array(
            'class' => true,
            'data-id' => true,
            'data-block' => true,
            'data-type' => true
        );
        // 可根据实际需要添加其他标签和属性
    }
    return $allowed;
}, 10, 2);

// 确保REST API返回原始内容，避免自动解析修改
add_filter('rest_prepare_page', function($response, $post) {
    $response->data['content']['raw'] = $post->post_content;
    return $response;
}, 10, 2);

注意：此方法会降低站点的安全防护等级，仅在你完全信任所有内容提交来源时使用。

内容的提问来源于stack exchange，提问作者Ege Hurturk