把一个 block 加进 catalog_product_view.xml，清了浏览器缓存却没有出现；或者 remove 指令对某个页面始终无效。layout XML 是按 handle 合并的，文件存在并不代表当前请求加载了它。先确定 handle，再谈缓存。

文件名必须对应当前 handle

商品详情常用 catalog_product_view，分类页是另一个 handle，自定义 controller 还会按 frontName、controller、action 生成名称。打开开发者工具或在测试环境启用布局调试，确认实际 handle。不要靠 URL 字面猜文件名。

reference 的 name 不是模板别名

<referenceContainer name="content">
    <block class="VendorModuleBlockNotice"
           name="vendor.product.notice"
           template="Vendor_Module::notice.phtml" />
</referenceContainer>

referenceContainer 必须指向已经存在的 container name。主题或扩展改过结构后，网上示例中的 name 可能不存在。搜索合并来源里的声明，注意同名 block 可能被后加载模块移除。

清正确的缓存

bin/magento cache:clean layout block_html full_page
bin/magento cache:status

XML 结构变化通常不需要删除所有 generated 代码。生产环境清 full_page 会影响命中率，应该在维护窗口或精确 purge。若文件根本没有部署到当前 release，清多少次都无效。

确认主题与模块加载顺序

查看当前 store 使用的主题及其父主题，确认 XML 放在正确模块目录。模块之间需要顺序时，在 module.xml 声明 sequence，但不要为了“让我的 XML 最后执行”随意依赖大量模块。

生成了却看不见，是另一类问题

页面源码里已经有目标 HTML，而视觉上没有变化，应检查模板条件、CSS 的 display:none、响应式断点和 JavaScript 是否把节点移走。Block 类构造失败或模板文件路径错误时，则查看 var/log/exception.log 与 PHP 日志。把一个带固定文本的最小模板放入相同位置，可以快速区分数据逻辑和布局结构。

修复后不要只刷新已经打开的页面。用无痕窗口访问同一 store view，再测试不同商品类型和客户组。若 XML 仅对某个 product attribute 条件生效，确认条件数据在当前 store scope 存在。最终以布局结构中出现目标 block、模板成功渲染、FPC 命中后仍显示正确为完成标准。