10 篇博文 含有标签「FSE」

在为客户开发 WordPress Block Theme 时反复遇到这五个问题，每次排查都花了不少时间。整理成指南，帮助同样在做 FSE 开发的同学快速定位。

TL;DR​

五个问题按频率排序：文件修改不生效（数据库缓存覆盖文件）、块嵌套错乱（注释未关闭）、子主题内容不渲染（缺少 post-content 块）、SVG 图标消失（WP_Filesystem 被插件污染）、WP-CLI 邮件失败（SMTP 插件在命令行不生效）。每个场景都给出可直接复用的排查命令。

在为客户构建 WooCommerce Block Theme 时遇到了这四个与 WooCommerce 相关的问题，每个都与 FSE 架构和 WooCommerce 的块系统有关。记录排查过程，帮助同样在做 WooCommerce 主题开发的同学避坑。

TL;DR​

四个 WooCommerce Block Theme 开发中的常见问题：块重命名导致 core/missing（升级后块名加了 -block 后缀）、修改 shop slug 后产品归档 404（rewrite 缓存未刷新）、模板 HTML 与 Gutenberg save 不匹配（动态块验证失败）、Cart/Checkout 模板未自动分配（需要手动指定）。每个场景给出可直接复用的修复方案。

在为客户开发 WordPress FSE Block Theme 并集成 WooCommerce 时，遇到 4 个 WooCommerce 静默篡改主题样式的陷阱。每个都很隐蔽，排查耗时。记录根因与解法，帮助同样开发 FSE + WooCommerce 主题的开发者避坑。

TL;DR​

1. 字号预设覆盖：WooCommerce 注册 small/medium/large/x-large 四个预设覆盖 theme.json，用 h-1~h-6 自定义 slug 规避
2. font-size class 连字符：has-h-1-font-size(48px) vs has-h1-font-size(20px)，手写 HTML 必须带连字符
3. contrast 颜色反转：--wp--preset--color--contrast 被 WooCommerce 改为浅色（#f8fafc），白色文字完全不可见
4. ul.products 伪元素：WooCommerce 注入 ::before/::after 破坏 CSS Grid 布局，需 display:none 清除

在为客户开发 WordPress FSE Block Theme 时，遇到风格预览显示异常和首页编辑白屏两个问题。记录根因与解法。

TL;DR​

1. Style variation 的 palette/gradients 是整体替换而非合并，只写 1 个颜色会丢失其余全部 -- 必须补全完整列表，只改需要变化的颜色。
2. front-page.html 模板硬编码 pattern 会导致 Site Editor 编辑白屏，且用户无法在编辑器中调整布局 -- 应改为页面内容驱动。

在为客户开发 WordPress FSE Block Theme 时发现：博客列表页的卡片悬浮时文字区域发生偏移，但卡片外框不动，视觉上非常违和。记录根因与解法。

TL;DR​

通用卡片 hover 选择器 .wp-block-columns .wp-block-column > .wp-block-group:hover 会匹配到卡片内部嵌套的文字 group，导致悬浮时内层文字偏移而外层卡片不动。修复方式：用 .wp-block-post-template 前缀重置内层 group 的 hover 效果。

在为客户开发 WooCommerce FSE Block Theme 时遇到这两个问题：Cart Block 空车时页面白屏、商品无特色图片时卡片高度塌陷。记录根因与解法。

TL;DR​

1. Cart Block 必须显式声明 filled-cart-block 和 empty-cart-block 子块，否则空车时无任何内容输出。
2. 商品无特色图片时，FSE 的 post-featured-image 块渲染为空字符串，导致卡片高度塌陷。通过 post_thumbnail_html filter 补上 WooCommerce 占位图。

在为客户开发 WordPress FSE 主题时遇到此问题，记录根因与解法。

TL;DR​

Gutenberg 升级后，gradient 的 CSS class 命名规则从 has-{slug}-gradient 变为 has-{slug}-gradient-background。手写 Pattern HTML 中的旧 class 与 Gutenberg 验证逻辑不匹配，导致 Site Editor 报错。解决方案是批量替换 class 名称。

TL;DR​

WordPress FSE Group 块的 layout 属性会自动生成 is-layout-* CSS 类，这些类的样式优先级高于普通自定义 CSS，导致尺寸设置失效。解决方案：1) 块注释中使用 "layout":{"type":"default"} 避免生成额外布局类；2) CSS 中使用 !important 强制覆盖；3) 关键：添加 padding: 0 !important 清除 Group 块默认内边距。

在为客户开发 WordPress FSE 企业主题时，发现 Footer 区块在多个 Style Variation 下文字几乎不可见。本文记录从 WCAG 对比度诊断到引入语义色、处理全局样式覆盖的完整修复过程。

TL;DR​

问题：FSE 主题的 contrast 颜色 token 语义混乱，浅色主题中 contrast ≈ 浅灰 ≈ base（白色），导致 Footer 对比度仅 1.05:1。

解法：

1. 引入 surface 语义色，专用于深色区块背景
2. 删除 wp_global_styles 中的覆盖样式
3. 所有 Style Variations 同步添加 surface 定义

结果：对比度从 1.05:1 提升至 15.8:1（WCAG AAA 级）。

在为客户开发 WordPress FSE 主题时，频繁遇到 Block Pattern 验证失败问题。本文总结 5 种常见原因与解决方案。

TL;DR​

块验证失败通常是以下原因之一：颜色 slug 未定义、JSON 重复 key、Style Variation 调色板覆盖、HTML 属性与块注释不一致、全局样式覆盖 theme.json。逐一排查即可解决。