跳到主要内容

修改 WordPress Block Theme 不生效？FSE 开发 5 大难题排查指南

· 阅读需 8 分钟
CCLEE
CCLEE

在为客户开发 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 注释标记块的边界：

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- 内容 -->
<!-- /wp:group -->

当容器块（如 wp:group、wp:columns）缺少关闭注释 <!-- /wp:group --> 时，Gutenberg 的 parse_blocks() 会将后续所有块视为该容器的子块。后果：

  1. 父块的 save 输出为空
  2. 触发 Block validation failed
  3. 后续所有块的嵌套关系全部错位

解决方案​

排查：在浏览器控制台检查块树层级：

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 块：

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">

  <!-- 模板固定结构（hero、sidebar 等） -->

  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->

  <!-- 更多固定结构（CTA、footer 引用等） -->

</div>
<!-- /wp:group -->

排查"改了没效果"时，按以下顺序确认：

  1. 模板文件是否包含 <!-- wp:post-content /-->
  2. 你修改的是模板文件还是页面内容——两者控制不同的内容区域
  3. 模板中内联的 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 链的功能（如邮件、缓存预热等）。

联系合作