在为客户开发 WordPress Block Theme 时反复遇到这五个问题，每次排查都花了不少时间。整理成指南，帮助同样在做 FSE 开发的同学快速定位。
TL;DR
五个问题按频率排序：文件修改不生效（数据库缓存覆盖文件）、块嵌套错乱（注释未关闭）、子主题内容不渲染（缺少 post-content 块）、SVG 图标消失（WP_Filesystem 被插件污染）、WP-CLI 邮件失败（SMTP 插件在命令行不生效）。每个场景都给出可直接复用的排查命令。
场景一：改了主题文件，页面没变化
问题现象
修改了主题目录下的 theme.json、templates/*.html 或 parts/*.html，刷新页面无变化。甚至 git pull 更新了代码，前端仍然显示旧样式。
FSE 主题的模板和全局样式会被 Site Editor 保存到数据库——wp_template、wp_template_part、wp_global_styles 三种自定义文章类型。WordPress 读取时数据库版本优先于文件版本。即使你改了文件，只要数据库里有对应记录，就会用数据库的。
解决方案
不同文件类型对应不同的清理方式：
| 修改内容 | 清理方式 |
|---|
templates/*.html | 清 wp_template |
parts/*.html | 清 wp_template_part |
theme.json | 清 wp_global_styles + 缓存 |
patterns/*.php | 直接生效，无需清理 |
一键清理所有数据库模板缓存：
# 本地 Docker 环境
docker exec wp_cli bash -c 'wp post delete $(wp post list --post_type=wp_template --format=ids --allow-root) --force --allow-root'
docker exec wp_cli bash -c 'wp post delete $(wp post list --post_type=wp_template_part --format=ids --allow-root) --force --allow-root'
docker exec wp_cli bash -c 'wp post delete $(wp post list --post_type=wp_global_styles --format=ids --allow-root) --force --allow-root'
docker exec wp_cli wp cache flush --allow-root
如果 theme.json 修改后仍不生效，先验证 JSON 格式是否有语法错误（如尾随逗号，JSON 规范不允许）：
docker exec wp_cli wp eval 'echo json_encode(json_decode(file_get_contents(get_template_directory() . "/theme.json")));' --allow-root
# 返回空字符串 → JSON 有语法错误
注意事项
- 开发期禁止在 Site Editor 中保存，避免产生数据库覆盖
- 生产环境清理前确认 Site Editor 中没有自定义修改需要保留
patterns/*.php 不受此问题影响——Pattern 注册走 PHP 代码，不经过数据库- Site Editor 保存的
wp_global_styles 如果 JSON 损坏，会导致全站 WP_Theme_JSON_Resolver 解析错误，表现为所有页面样式崩溃
场景二：Site Editor 显示"尝试恢复"，页面布局全乱了
问题现象
Site Editor 中 Pattern 显示"尝试恢复"（Attempt Recovery），保存后页面布局完全错乱。某些块被错误地嵌套在其他块内部，层级关系与源码不一致。
WordPress 块编辑器使用 HTML 注释标记块的边界：
<div class="wp-block-group">
当容器块（如 wp:group、wp:columns）缺少关闭注释 <!-- /wp:group --> 时，Gutenberg 的 parse_blocks() 会将后续所有块视为该容器的子块。后果：
- 父块的 save 输出为空
- 触发 Block validation failed
- 后续所有块的嵌套关系全部错位
解决方案
排查：在浏览器控制台检查块树层级：
wp.data.select('core/block-editor').getBlocks()
检查返回的块树结构，确认每个容器块的 innerBlocks 是否符合预期。如果一个 group 块内部包含了不应该在里面的块，大概率是前面某个容器缺少关闭注释。
修复：打开 Pattern 源文件，逐个检查每个 <!-- wp:xxx --> 都有对应的 <!-- /wp:xxx -->。建议在编辑器中搜索 <!-- wp: 和 <!-- /wp:，计数确认数量一致。
预防技巧
使用支持括号匹配的编辑器（如 VS Code），配合 Block Comment 高亮插件，可以在编写时立即发现未关闭的注释。对于复杂的 Pattern，建议先写骨架结构（所有开闭注释配对），再填充内容。
场景三：子主题覆盖模板后，编辑器内容消失了
问题现象
创建子主题覆盖父主题模板后，在 WordPress 页面编辑器中输入的内容（文本、图片等）在前端完全空白。但模板文件中硬编码的 Pattern（如 hero 区域、CTA 区块）正常显示。
FSE 模板通过 <!-- wp:post-content /--> 块来渲染页面编辑器中的 post_content。如果子主题覆盖的模板文件中没有这个块，WordPress 不知道在哪里输出页面内容。
结果就是：模板的固定结构（header、hero、sidebar）正常显示，但编辑器里写的内容全部丢失。
解决方案
确保子主题模板包含 post-content 块：
<div class="wp-block-group">
</div>
排查"改了没效果"时，按以下顺序确认：
- 模板文件是否包含
<!-- wp:post-content /-->
- 你修改的是模板文件还是页面内容——两者控制不同的内容区域
- 模板中内联的 cover block 由模板文件控制，与数据库
post_content 无关
场景四：SVG 图标突然消失，但文件还在
问题现象
主题中使用 WP_Filesystem 读取 SVG 图标文件，突然所有 SVG 图标消失。直接访问 SVG 文件 URL 返回正常内容，但页面上图标位置是空的。
WordPress 的 $wp_filesystem 全局变量默认使用 WP_Filesystem_Direct（直接读写本地文件）。某些插件（备份、安全类）在初始化时会将 $wp_filesystem 替换为 WP_Filesystem_ftpsockets 或 WP_Filesystem_SSH2。
FTP/SSH 适配器通过远程连接读取文件，对本地路径（如 /var/www/html/wp-content/themes/...）无法正确访问，返回空字符串。由于替换发生在全局作用域，所有使用 WP_Filesystem 的主题和插件代码都受影响。
解决方案
第一步——诊断：检查当前 $wp_filesystem 的实际类型：
# 本地 Docker 环境
docker exec wp_cli wp eval 'global $wp_filesystem; echo get_class($wp_filesystem);' --allow-root
# 返回 WP_Filesystem_Direct → 正常
# 返回 WP_Filesystem_ftpsockets 或其他 → 已被污染
第二步——定位污染源：逐个禁用插件，检查哪个插件替换了适配器：
docker exec wp_cli wp plugin deactivate <plugin-name> --allow-root
docker exec wp_cli wp eval 'global $wp_filesystem; echo get_class($wp_filesystem);' --allow-root
# 重复直到返回 WP_Filesystem_Direct
第三步——代码兜底：在主题中加 file_get_contents() 作为 fallback：
function mytheme_get_svg( $path ) {
global $wp_filesystem;
// 优先使用 WP_Filesystem
if ( $wp_filesystem && method_exists( $wp_filesystem, 'get_contents' ) ) {
$content = $wp_filesystem->get_contents( $path );
if ( $content ) {
return $content;
}
}
// WP_Filesystem 失败时回退到直接读取
if ( file_exists( $path ) ) {
return file_get_contents( $path );
}
return '';
}
注意事项
file_get_contents() 在某些受限主机可能被 disable_functions 禁用，但 VPS 和 Docker 环境通常可用- 根治方案是定位并处理污染源插件，代码兜底只是临时方案
- 此问题具有隐蔽性——SVG 文件本身完好，直接访问正常，只有在 PHP 中通过
WP_Filesystem 读取时才返回空
场景五：命令行发邮件失败，网页端正常
问题现象
通过 wp eval 在命令行调用 wp_mail() 发送邮件，始终失败。但通过 Web 请求触发的邮件（用户注册、联系表单）发送正常。WP Mail SMTP 等插件已正确配置 SMTP。
SMTP 插件通过 Hook 拦截 wp_mail()，将发信通道从 PHP sendmail 切换到 SMTP 服务。但这些插件的 Hook 注册依赖 WordPress 完整启动流程——特别是 wp_loaded 之后的阶段。
WP-CLI 的 wp eval 虽然加载了 WordPress 核心，但部分插件 Hook 在 CLI 环境下不会被注册。wp_mail() 回退到 PHP sendmail，而大多数服务器没有配置 sendmail，导致发送失败。
解决方案
方法一——Web 请求测试：在主题中临时添加测试路由，通过浏览器触发：
// 临时添加到 functions.php，测试完立即删除
add_action( 'wp_loaded', function() {
if ( ! isset( $_GET['test_mail'] ) ) return;
if ( '1' !== $_GET['test_mail'] ) return;
$result = wp_mail( '[email protected]', 'SMTP Test', 'Test email body' );
var_dump( $result ); // true = 发送成功
exit;
} );
访问 https://yoursite.com/?test_mail=1 触发测试。
方法二——eval-file 确保完整加载：
cat > /tmp/test-smtp.php << 'EOF'
<?php
require_once ABSPATH . 'wp-load.php';
do_action('wp_loaded');
$result = wp_mail('[email protected]', 'CLI SMTP Test', 'Test body');
echo $result ? "Sent\n" : "Failed\n";
EOF
docker exec wp_cli wp eval-file /tmp/test-smtp.php --allow-root
最佳实践
生产环境中，邮件发送验证应通过 Web 请求测试。WP-CLI 适合定时任务和批量操作，但不适合验证依赖完整 WordPress Hook 链的功能（如邮件、缓存预热等）。
