解决 WordPress Gutenberg 多 Shortcode 解析不稳定问题的实践记录

一、背景

在使用 WordPress 区块编辑器（Gutenberg）编写技术博客时，我经常需要在一篇文章中同时包含多种代码块，例如：

SQL 查询（SQL）
Go 示例代码（Go）
PHP 代码（PHP）
说明文本（Text）

通常一篇文章中会包含 10 个左右的代码块混合使用。

早期使用经典编辑器时，这类内容是非常稳定的，但在 Gutenberg 中，我遇到了一个比较典型的问题：

多个 sql / go / php shortcode 在“整篇粘贴”时偶尔解析异常

二、问题现象

在使用 SyntaxHighlighter Evolved 时，我的写作方式通常是：

在本地 txt 文件中写完整文章
包含多个 sql、go、php 块
直接 Ctrl + V 粘贴到 WordPress

但在 Gutenberg 中会出现以下现象：

❌ 异常情况
第一次发布后：
部分 SQL 块被解析成 code 或 <code>
部分 shortcode 未正确渲染
再次编辑文章后重新粘贴：
又恢复正常

这种“第一次异常、第二次正常”的行为非常困扰批量写作。

三、根本原因分析

问题本质不在插件，而在 Gutenberg 的自动解析机制：

Gutenberg 行为特点：

当你：

一次性粘贴整篇包含多个 shortcode 的内容

系统会：

自动识别 sql、go 等 shortcode
自动拆分为多个区块
同时尝试解析 HTML / inline code
在某些情况下误判反引号（`）为 inline code

导致：

orders → orders
再被转义 → <code>orders</code>

四、稳定写作方案（核心）

经过多次测试，最稳定的方法是：

❗不要让 Gutenberg “猜区块结构”，而是提前固定结构

五、兼容方案（用于旧写法或批量粘贴）

在仍使用 sql / go / php shortcode 的情况下（例如历史文章或本地 txt 模板），可以采用以下方式：

Step 1：创建 Shortcode 区块

在 WordPress Gutenberg 编辑器中：

点击「+ 添加区块」
选择 Shortcode（简码）区块
Step 2：粘贴整篇文章

将本地 txt 中的完整内容一次性粘贴，例如：

select count(*) from orders;

说明文字……

fmt.Println("hello")

select * from users;

Step 3：发布或预览验证

检查：

shortcode 是否正确解析
是否出现 code 污染
SQL / Go 是否正常渲染
⚠️ 注意事项

该方式属于：

兼容旧 shortcode 写作方式

不建议用于新文章长期使用。

六、（新增）现代推荐方案（强烈推荐）
Step 1：使用 SyntaxHighlighter Code Block

/syntax

插入：

SyntaxHighlighter Evolved Code Block

Step 2：粘贴代码

例如：

fmt.Println(“hello”)

Step 3：选择语言
SQL
Go
PHP
优点
无 shortcode 解析问题
不会出现 code 污染
完全 Gutenberg 原生支持
更稳定

七、推荐写作规范（长期使用）

为了保证技术博客在 Gutenberg 环境下的稳定性，建议统一以下规范。

1.代码块规范（推荐新标准）

所有新文章统一使用 SyntaxHighlighter Evolved 的 Code Block（Gutenberg 版本）：

| 类型 | 写法 |
| — | ———————————- |
| SQL | SyntaxHighlighter Code Block + SQL |
| Go | SyntaxHighlighter Code Block + Go |
| PHP | SyntaxHighlighter Code Block + PHP |

不再作为主要方式使用：

...

...

仅用于历史文章兼容。

2.粘贴规范

推荐统一使用：

Ctrl + Shift + V（纯文本粘贴）
或使用 Visual Studio Code 作为中转编辑器

3.区块规范（新版）

| 操作 | 推荐 |
| —————————- | ——— |
| SyntaxHighlighter Code Block | ✅ 推荐（主方式） |
| Shortcode 区块（） | ⚠️ 仅兼容用途 |
| Paragraph 粘贴 | ❌ 避免 |

八、为什么这个方案更稳定

核心原因是：

1.不再依赖 Gutenberg 自动解析

避免：

shortcode 自动拆分错误
首次渲染异常

2.代码结构由 Block 控制

WordPress Gutenberg 直接使用：

Code Block
SyntaxHighlighter Block

而不是 shortcode 推断

3.避免 HTML 污染

彻底解决：

code 误解析
<code>
反引号污染

九、总结（新版）

在 Gutenberg 环境下编写技术博客（SQL / Go / PHP 混合内容）时，核心原则升级为：

🧠 新核心原则：

先用 Block 结构保证渲染稳定，再粘贴内容

推荐流程（最终版）

1.使用 SyntaxHighlighter Code Block（/syntax）
2.一次性粘贴整篇文章（txt）
3.删除自动生成的 Shortcode 区块
4.保留 Code Block 渲染代码
5.发布前预览检查

十、延伸优化（可选）

如果后续希望进一步优化体验，可以考虑：

Prism 高亮（更现代）
代码复制按钮
行号显示优化
主题统一代码样式

十一、发布前预览与兜底检查（重要）

在完成文章编辑后，即使已经按照规范使用 SyntaxHighlighter Code 区块（SQL / Go / PHP 等），仍然建议增加一个“发布前预览步骤”，用于最终兜底检查。

在 WordPress 的 Gutenberg 编辑器中，可以通过以下方式进行预览验证：

1.使用预览功能

在发布前点击：

「预览（Preview）」
或「在新标签页中预览」

确认页面渲染效果是否正常。

重点检查：

SQL 是否仍然保持完整结构
是否出现 code 或 <code> 污染
多个 sql / go / php 是否正确渲染

2.快速滚动检查所有代码块

对于一篇包含约 10 个代码块的技术文章，建议在预览页快速检查：

SQL 查询块是否完整
Go 示例是否正常换行
PHP 代码是否未被截断
文本说明是否错位

这个过程通常只需要 10～20 秒，但可以有效避免发布后返工。

3.发现问题的处理方式

如果在预览中发现问题：

不要直接整篇重新粘贴
只针对异常的 shortcode 区块重新粘贴内容
再次预览确认修复结果

4.最终发布原则

只有在预览确认以下条件后，才进行发布：

所有代码块渲染正常
无 code 或 HTML 转义污染
多语言代码块结构一致
页面整体排版正常

5.这一步骤的意义

这一预览步骤的核心作用是：

在发布前拦截 Gutenberg 自动解析带来的偶发问题

相比“发布后再修复”，可以显著减少返工次数，提高整体写作效率与稳定性。