EP05. "elementor-debug-render 渲染故障排查"

• Elementor 页面突然一片空白、编辑器能改但前台看不到最新内容、atomic widget 什么都不渲染——这类问题往往不是代码坏了，而是缓存、JSON 数据、schema 校验这几个环节其中一个卡住了，elementor-debug-render 就是帮你按"问题出在哪个环节"分层排查，不用瞎猜
• 这是 mekko-digital/elementor-skills 开源 skill 包的其中一个，专门做诊断（不生成代码），先分 4 大类定位问题出在哪里，再对照更细的排查清单
• skill 本体压在 80 行以内，完整的分步骤检查清单另外放在 resources/debug-checklist.md，真的要深入排查才读
• 前置知识：先看过 Overview 系列「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」两篇；也建议知道怎么打开浏览器开发者工具看 Console/Network

重点内容

这个 Skill 是做什么的

elementor-debug-render 是诊断型 skill，跟同一个包里偏"造东西"的脚手架型 skill（elementor-widget-create、elementor-form-action、elementor-dynamic-tag、elementor-theme-builder-location）性质不同——它不生成新代码，而是根据故障现象，把问题定位到编辑器、预览、前台三个环节中的哪一个，再往下细查。

适合用在：

• Elementor 编辑器画布空白，但设置面板还在
• 编辑器预览 iframe 空白，但侧边面板功能正常
• 前台页面显示的内容是旧的，或者干脆空白，但编辑器预览正常
• _elementor_data 疑似损坏，或者 atomic 4.0（e- 开头）的元素渲染不出来

不适合用在：

• widget 本来就还没写，不是"坏了"而是"根本不存在"——那是 elementor-widget-create 的工作
• 不确定某个功能是免费版还是 Pro 版才有——先查 elementor-feature-lookup
• 确认修好之后要部署到真实站点验证——那是 elementor-deploy-verify 的工作，这个 skill 只管排查、不管部署

第一步：先判断问题出在哪个环节

第二步：核对数据本身

Elementor 页面在 wp_postmeta 表里存的关键字段：

• _elementor_data — 元素树的 JSON。如果这段 JSON 读不出来，编辑器会悄悄丢掉整个页面，不会报错提示
• _elementor_edit_mode — 必须是 'builder'，Elementor 才会接管这个页面
• _elementor_version、_elementor_template_type、_elementor_page_settings
• _elementor_css — 生成好的内联 CSS，页面保存时会重新生成（elementor-free/elementor/core/files/css/post.php，META_KEY = '_elementor_css'）
• 📌 元素渲染缓存的 key 是一个全局 option（_elementor_element_cache_unique_id，见 modules/element-cache/module.php:17），不是 post meta——要清掉所有元素缓存，改/清这个 option 就够了

用 WP-CLI 排查：

# 查看某篇文章的 Elementor 数据（配合 jq 格式化）
wp post meta get <id> _elementor_data | jq .

# 重新生成 CSS
wp elementor flush_css

第三步：缓存重建（前台问题最常见的修法）

按顺序、逐级升级：

1. 在编辑器里打开页面，保存一次——会重新生成 _elementor_css、元素缓存、资源清单
2. Elementor → Tools →「重新生成 CSS 与数据」（Regenerate CSS & Data）
3. Element-cache 模块（Elementor\Modules\ElementCache\Module）：走 Tools 清一次，或者直接停用——用 wp option update elementor_element_cache_ttl disable 把选项设成 disable（设置项在 element-cache/module.php:130，更新这个 option 会自动清空缓存，见第 153 行）；没有对应的 ELEMENTOR_* 常量可以设
4. 页面资源加载器：每篇文章保存时会记住自己要加载哪些 JS/CSS。如果某个 widget 的 JS 没加载，通常是这个 widget 是保存之后才用代码加进页面的——重新保存一次页面就好
5. 有装对象缓存/页面缓存插件的话，改完内容记得手动 flush 一次

Atomic 4.0（e- 开头元素）的特殊坑

源码根目录：elementor-free/elementor/modules/atomic-widgets/

• Atomic widget 的元素类型都是 e- 开头（e-button、e-heading、e-flexbox 等），跟经典 widget 能混用在同一页面，但两者不共用控件管线
• define_props_schema() 是唯一的真相来源——保存的值如果已经不符合 schema，加载时会被静默丢弃（校验逻辑在 PropTypes/*::validate()），不会报错
• Has_Template trait 要求同目录下有对应的 .twig 文件，缺文件的结果是渲染出空内容，不会抛 PHP 错误
• Atomic 的样式是从 Style_Definition 生成 CSS class 的。样式没生效时，检查元素上的 classes 属性和对应断点的 styles_schema
• Atomic 表单（e-form）只有 Pro 启用 且 e_pro_atomic_form 这个实验特性打开时才会加载（atomic-widgets/module.php:288）
• Atomic 动态标签走的是另一条管线（atomic-widgets/dynamic-tags/）；经典动态标签会自动被 Dynamic_Tags_Converter 适配，转换失败的话绑定会直接掉——细节见 elementor-dynamic-tag 这篇笔记

都查不出问题的话

• Safe mode：访问 ?elementor-mode=safe（免费版内建的 safe-mode/ 模块）
• 临时停用 Pro——很多"免费"widget 其实被 Pro 覆盖了实现（比如 Posts 走 Loop、Form 走 atomic）
• 检查 elementor/widget/render_content（注意是单数 widget，widget-base.php:662）和 elementor/element/before_section_start 这类 filter，其他插件很容易乱勾这些 hook
• 更完整的分步骤清单见 resources/debug-checklist.md

resources/debug-checklist.md 补充要点

skill 本体给的是分类判断，这份完整清单是逐项对照表，挑几个 SKILL.md 里没细讲的补充点：

• 编辑器画布空白：在 Console 跑 elementor.elements.toJSON() 看元素是不是根本没被加载；Network 面板查 elementor_ajax 的 save_builder 动作，找到最后一次成功保存的时间点；也要试着换个用户角色，edit_with_elementor 这个权限门槛可能把东西隐藏了
• _elementor_data 损坏：改之前先备份 wp post meta get <id> _elementor_data > backup.json，用 jq . backup.json 验证 JSON 合不合法；常见损坏原因是服务器端过滤器注入了 UTF-8 BOM、wp_kses 把引号吃掉、某个整合插件把内容重复编码了一次；Elementor 的数据在文章修订版本（revision）里也有存，可以用 wp post revisions list <id> 找回来
• Pro 覆盖悄悄换掉免费 widget：Posts、Form、Carousel 这几个免费 widget 在 Pro 启用时会被替换实现——如果 bug 只在装了 Pro 时才重现，先怀疑 elementor-pro/modules/posts/、loop-builder/、atomic-form/ 这几个模块，临时停用 Pro 确认
• 容易被第三方插件乱勾的 hook：除了 SKILL.md 提到的两个，还有 elementor/frontend/the_content、elementor/widget/print_template、elementor/document/save/data、elementor/files/css/parse_content_css——在 wp-content/plugins 里搜这几个名字，经常能挖出真凶

怎么安装

这个 skill 是 mekko-digital/elementor-skills 这个开源仓库打包的 8 个技能之一，用 Claude Code 的插件市场机制安装，装一次全部到位：

Claude Code（推荐：走插件市场）：

claude plugin marketplace add mekko-digital/elementor-skills
claude plugin install elementor-skills@elementor-skills-marketplace

Claude Code（手动方式）： 把 skills/elementor-debug-render 这个文件夹复制到 ~/.claude/skills/（所有项目都能用）或专案底下的 ./.claude/skills/（只想在这个项目用）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传 skills/elementor-debug-render 这个文件夹（打包成 zip，内含 SKILL.md）——插件市场机制是 Claude Code 专属的，Desktop 端目前只能手动上传单个 skill。

常见错误

• ❌ 前台显示旧内容就直接怀疑代码有 bug，跳过缓存重建步骤——绝大多数"只有前台坏"的情况根本不是代码问题，是 CSS/缓存过期，先按第三步的顺序重建一遍
• ❌ atomic widget 渲染不出东西就直接改 PHP 逻辑——先怀疑 define_props_schema() 和实际保存的值对不上，被静默丢弃了，这种情况改 render() 没用
• ❌ 排查 _elementor_data 损坏之前没先备份——wp post meta update 这类操作是覆盖性的，改错了想找回原值只能靠文章修订版本
• 📌 CDN 有时候会忽略 querystring，Elementor 靠 ?ver= 参数强制刷新缓存，如果 CDN 不认这个参数，页面可能一直拿到旧版本
• 💡 确认问题原因、也修好之后，用同一个 skill 包里的 elementor-deploy-verify 在真实站点上复现/确认修复（建一个页面、无头渲染、看是否还报错）

Sources

官方文档：

1. elementor-skills（GitHub 仓库）— https://github.com/Mekko-Digital/elementor-skills
2. elementor-debug-render SKILL.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-debug-render/SKILL.md
3. elementor-debug-render debug-checklist.md — https://github.com/Mekko-Digital/elementor-skills/blob/main/skills/elementor-debug-render/resources/debug-checklist.md