记一次由 WPCode 简码引发的 WordPress 500 致命错误排查全记录

背景
近日，在维护博客时遇到一个棘手的问题：某一篇特定的文章详情页面直接显示“此站点遇到了致命错误”（500 Internal Server Error），而其他的文章详情页面打开都是完全正常的。
单一页面崩溃，通常是该页面独有的元素（如特定的短代码、区块或内容）触发了 PHP 致命错误。

1. 查看错误日志，锁定“案发武器”

第一反应是查看服务器的 debug.log，发现了如下致命错误记录：

[23-Jun-2026 13:13:47 UTC] PHP Fatal error:  Cannot redeclare custom_desc_and_ads_inserter() (previously declared in /data/wwwroot/www.shuijingwanwq.com/wp-content/plugins/insert-headers-and-footers/includes/class-wpcode-snippet-execute.php(419) : eval()'d code:6) in /data/wwwroot/www.shuijingwanwq.com/wp-content/plugins/insert-headers-and-footers/includes/class-wpcode-snippet-execute.php(419) : eval()'d code on line 451

[23-Jun-2026 13:13:47 UTC] PHP Fatal error:  Cannot redeclare custom_desc_and_ads_inserter() (previously declared in /data/wwwroot/www.shuijingwanwq.com/wp-content/plugins/insert-headers-and-footers/includes/class-wpcode-snippet-execute.php(419) : eval()'d code:6) in /data/wwwroot/www.shuijingwanwq.com/wp-content/plugins/insert-headers-and-footers/includes/class-wpcode-snippet-execute.php(419) : eval()'d code on line 451

日志分析：

• Cannot redeclare custom_desc_and_ads_inserter()：这是一个经典的 PHP 错误，意味着同一个函数名被声明了两次。
• 路径指向 insert-headers-and-footers（即 WPCode 插件）内部的 class-wpcode-snippet-execute.php 文件。
• 关键在于 eval()'d code：说明这段导致错误的代码不是写死在文件里的，而是通过 WPCode 插件动态执行的代码片段。

2. 应急处理与错误线索排查（此路不通）

为了先恢复页面的访问，我决定先在后台禁用 WPCode 中对应的这个代码片段。

禁用后，页面确实不报 500 错误了，但这只是治标不治本。接下来开始寻找根本原因：

• 怀疑对象 1：Code Pro 代码区块
  我想起在这篇报错的文章中，使用了 Code Pro 插件展示了一段 PHP 代码，里面恰好包含了 custom_desc_and_ads_inserter 函数的定义。
  行动：我将代码块中的函数名进行了重命名，保存后刷新页面，依然报错 500。
  进一步行动：我甚至直接将整个 Code Pro 代码区块从文章中删除，保存后刷新页面，竟然还是报错 500！
  反思： 既然删除了文章中的纯展示代码依然报错，说明导致函数重复声明的元凶不在纯展示代码块。需要重新排查了。

3. 定位简码与再次踩坑

既然排除了 Code Pro 区块的嫌疑，目光重新回到 WPCode 插件本身。我重新审视了这篇文章的内容，发现文章中直接包含了 WPCode 的简码调用：wpcode。如图4

之前 wpcode 不在古腾堡编辑器专用的“简码区块”中时，前台页面与后台编辑器都报错。
行动：我将原本直接写在文本中的 wpcode 提取出来，放到了古腾堡编辑器专用的“简码区块”中。
结果：前台页面正常了！但是，后台编辑器仍然报错！
这说明问题并非出在区块解析层面，而是这个简码本身的执行逻辑存在冲突。WPCode 插件在处理该简码时，可能由于代码片段内容与当前环境的冲突，导致内部 eval() 逻辑将代码执行了两次。

4. 最终解决方案

在尝试了多种区块组合均无效后，为了彻底阻断 WPCode 对这段代码的异常执行，我采取了最直接有效的方案。由于重新启用 WPCode 代码片段会导致后台编辑器无法进入，因此必须按照以下特定顺序操作：

1. 保持 WPCode 中对应的代码片段为禁用状态（这样后台编辑器才能正常加载）。
2. 进入报错文章的编辑器。
3. 将文章内容中的简码 wpcode 直接修改为纯文本 wpcode。
4. 更新文章。
5. 回到 WPCode 插件设置，重新启用之前被禁用的代码片段（恢复全局功能可用）。

通过去除简码的方括号语法，WordPress 不再将其识别为可执行短代码，从而阻止了 WPCode 的 eval() 执行行为。刷新前台页面，文章完美加载，后台编辑也恢复正常，500 错误彻底消失！

总结与避坑指南

这次排查过程可谓一波三折，从一开始的错误方向到最终定位，总结出以下几点深刻教训：

1. Cannot redeclare 错误的本质： 一定是同一段代码被执行了多次。在 WPCode 等动态执行插件中，这通常意味着 eval() 逻辑被重复触发。
2. Code Pro 等高亮插件是安全的： 它们只是将代码作为纯文本进行语法高亮展示，不会在服务端通过 eval() 执行。删除它们无效，就能证明问题出在别处。
3. WPCode 简码的潜在风险： 在某些特定情况下，WPCode 的简码执行可能会导致代码片段被多次 eval()。如果遇到无法解决的重复声明错误，直接在内容中取消简码的执行（去掉方括号）是最有效的降级止损方案。
4. 防御性编程是底线： 无论插件执行机制如何，在 WPCode 中编写包含函数定义的代码片段时，务必使用 if ( ! function_exists( 'function_name' ) ) { ... } 进行包裹。即使被意外执行多次，也会被安全跳过，从而避免致命崩溃。