WordPress 区块编辑器 Gutenberg 完全指南：从入门到高效使用

引言：换了编辑器，效率反而降了

WordPress 5.0 把经典编辑器换成区块编辑器（Gutenberg）时，站长群体的抱怨到现在还没停。常见的吐槽是：写长文要不停插入区块、表格难用、老主题的短代码显示成一堆乱码。

但用了两年之后，大部分人的评价会反转。原因是区块编辑器的核心价值不在”写作”，而在结构化——它把内容拆成一个个可复用的语义单元，这对 SEO、对多端适配、对后期改版都是质的提升。

这一篇讲怎么用顺手，而不是怎么用。

原理分析：区块内容到底怎么存的

理解存储方式是解决大部分”奇怪问题”的钥匙。

区块编辑器把正文存成带 HTML 注释的 HTML：

<!-- wp:paragraph -->
<p>这是一段正文。</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":2} -->
<h2 class="wp-block-heading">这是二级标题</h2>
<!-- /wp:heading -->

<!-- wp:quote {"className":"is-style-large"} -->
<blockquote class="wp-block-quote is-style-large"><p>引用</p></blockquote>
<!-- /wp:quote -->

三个关键点：

1. 区块属性存在 JSON 里（{"level":2} 这种），所以直接 SQL 替换正文内容极易破坏 JSON，必须用 WP-CLI 的 search-replace（会重算序列化）。
2. 渲染是前端 PHP 做的（parse_blocks() → render_block()），不是浏览器渲染。所以即使不用区块编辑器，只要内容是这个格式，前台照样正常输出。
3. 经典内容（无注释的纯 HTML）会被包进”经典区块”（wp:classic 或 wp:freeform），这是老文章在区块编辑器里显示为”未转换的区块”的原因。

保姆级实操

一、20 个真正有用的快捷键

列表视图（List View）是长文写作最重要的功能：左侧面板里能看到整篇文章的区块树，直接拖拽调整顺序，比在正文里滚动找区块快得多。

二、常用区块的实战用法

• 标题区块：务必按 H2 → H3 的层级使用，不要为了字号大小跳级。这是 SEO 最基本的语义结构。
• 组区块（Group）：把几个区块打包成一个整体，方便统一设置背景色、内边距、宽屏对齐。做落地页必用。
• 列区块（Columns）：做左右分栏。移动端会自动堆叠，比自己写 CSS 靠谱。
• 表格区块：区块编辑器的表格确实弱（不能合并单元格），复杂表格建议用插件 “TablePress” 或直接写 HTML。
• 代码块区块：写技术文章必用，选语言后有语法高亮。
• 自定义 HTML 区块：放广告代码、iframe、短代码。
• 短代码区块：比自定义 HTML 更合适，因为不会被误清理。

三、可复用区块（Reusable Block）

把常用的板块（比如文末的”关注我们”、免责声明、作者信息）存成可复用区块：

选中区块 → 右上角三个点 → “添加到可复用区块” → 命名 → 保存。

之后在任何文章里通过 / + 名字插入。修改一个可复用区块，所有引用它的地方同步更新——这是它和普通复制粘贴最大的区别。

管理入口：后台左侧菜单”可复用区块”（或 /wp-admin/edit.php?post_type=wp_block）。

四、把老文章转成区块

打开老文章，会看到”此区块包含意外或无效的内容”提示。点”尝试恢复区块”或”转换为区块”。

批量转换：

wp post list --post_type=post --format=ids | while read id; do
  wp post update "$id" --post_content="$(wp post get $id --field=post_content)" 2>/dev/null
done

更可靠的做法是用插件 “Classic to Block Migration”。

五、禁用区块编辑器 / 回到经典编辑器

如果只是想回到经典编辑器：

// 完全禁用区块编辑器（恢复经典编辑器）
add_filter( 'use_block_editor_for_post_type', '__return_false' );

// 只对文章禁用，页面保留
add_filter( 'use_block_editor_for_post_type', function( $enabled, $post_type ) {
    return 'post' === $post_type ? false : $enabled;
}, 10, 2 );

或者装官方插件 Classic Editor（由 WordPress 官方维护，支持到 2024 年，官方承诺会继续维护）。

如果只是禁用小工具区块化（恢复老的小工具界面）：

add_filter( 'use_widgets_block_editor', '__return_false' );

六、编辑器报错排查

症状 1：编辑器白屏 / 无限加载

打开浏览器控制台看报错。常见原因：

• 主题或插件的 JS 报错（禁用插件逐个排查）；
• wp-editor 相关的 REST API 被安全插件挡了。检查 /wp-json/wp/v2/ 是否可访问：

bash
curl -I https://example.com/wp-json/wp/v2/posts

• 对象缓存插件返回了过期的编辑器资源。清缓存。

症状 2：”更新失败”提示

多半是 REST API 请求被拦截。常见原因：

• 站点开启了 HTTP Basic Auth（.htaccess 的 Require valid-user），会挡掉 REST 请求；
• 安全插件（Wordfence、安全狗）的防火墙规则；
• Cloudflare 的 Bot Fight Mode 误判。

排查：

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-WP-Nonce: $(wp eval-file /dev/null 2>/dev/null)" \
  -d '{"title":"test","status":"draft"}' \
  https://example.com/wp-json/wp/v2/posts

看返回是 401、403 还是 500。

症状 3：短代码在区块编辑器里显示成原始文本

短代码在 wp:shortcode 区块里前台正常，编辑器里显示原文，这是正常的。如果前台也显示原文，说明主题没执行 do_shortcode()，或者短代码所属插件被停用。

常见踩坑与失败案例

1. 案例一：批量替换文章里的某个品牌词，用了 SQL 的 REPLACE()，结果所有区块属性（{"level":2}）被破坏，前台标题全部变成普通段落。必须用 WP-CLI。
2. 案例二：站点开启了全站 HTTP 认证（Basic Auth），编辑器一直”更新失败”。解决：在认证规则里放行 /wp-json/ 和 /wp-admin/admin-ajax.php。
3. 可复用区块改了不同步：可复用区块有两种状态——”已同步”和”转换为常规区块”。误点了”转换为常规区块”就断开同步了，之后改动不会传播。
4. 案例三：用自定义 HTML 区块放了广告代码，某次更新后被 WordPress 的 wp_kses_post 过滤掉了 <script>。有脚本的广告要用”自定义 HTML”之外的方案，比如装专门的广告插入插件。
5. Gutenberg 和页面构建器冲突：同时装 Elementor 和 Gutenberg 编辑同一篇文章，最后保存的会覆盖另一方的结构。一篇文章只用一种编辑器。
6. 中文标点在代码块里：代码块里的中文引号会导致复制过去的代码报错。写技术文章时注意代码块里的引号要用英文半角。

总结

区块编辑器的核心逻辑是把内容拆成结构化单元，理解了这一点，剩下的就是熟练度问题。立刻能提升效率的三个动作：记住 / 快速插入和 Ctrl+Shift+D 复制区块；长文必用列表视图做大纲；重复出现的板块一律做成可复用区块。真要用不惯，use_block_editor_for_post_type 返回 false 就能回到经典编辑器，但代价是失去结构化带来的 SEO 和多端适配红利。另外记住一条铁律：区块内容含 JSON 属性，任何批量替换都必须走 WP-CLI，不能碰 SQL 的 REPLACE。