在为客户开发 WordPress Block Theme 时反复遇到这五个问题，每次排查都花了不少时间。整理成指南，帮助同样在做 FSE 开发的同学快速定位。
五个问题按频率排序：文件修改不生效（数据库缓存覆盖文件）、块嵌套错乱（注释未关闭）、子主题内容不渲染（缺少 post-content 块）、SVG 图标消失（WP_Filesystem 被插件污染）、WP-CLI 邮件失败（SMTP 插件在命令行不生效）。每个场景都给出可直接复用的排查命令。
在为客户构建 WooCommerce Block Theme 时遇到了这四个与 WooCommerce 相关的问题，每个都与 FSE 架构和 WooCommerce 的块系统有关。记录排查过程，帮助同样在做 WooCommerce 主题开发的同学避坑。
四个 WooCommerce Block Theme 开发中的常见问题：块重命名导致 core/missing（升级后块名加了 -block 后缀）、修改 shop slug 后产品归档 404（rewrite 缓存未刷新）、模板 HTML 与 Gutenberg save 不匹配（动态块验证失败）、Cart/Checkout 模板未自动分配（需要手动指定）。每个场景给出可直接复用的修复方案。
在为客户开发 WooCommerce FSE Block Theme 时遇到这两个问题：Cart Block 空车时页面白屏、商品无特色图片时卡片高度塌陷。记录根因与解法。
filled-cart-block 和 empty-cart-block 子块，否则空车时无任何内容输出。post-featured-image 块渲染为空字符串，导致卡片高度塌陷。通过 post_thumbnail_html filter 补上 WooCommerce 占位图。WordPress FSE 主题的 Pattern/Template 文件中，HTML 注释里的 JSON 属性如果某个字符串值缺少闭合引号 "，花括号数量仍然平衡，但 parse_blocks() 会静默将该块的 attrs 置为 null。Gutenberg 的 save 函数因此不输出 inline style，触发 Block validation failed。用 json.loads() 验证 JSON 合法性即可定位。