解决 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 自动解析带来的偶发问题
相比“发布后再修复”，可以显著减少返工次数，提高整体写作效率与稳定性。
