自定义Gutenberg块复制到新插件后无法显示的问题求助

1. 核对新插件的文件结构与路径 #

• 确认block.json的存放位置正确，比如新插件根目录下的blocks/[你的块名]/目录中，PHP主文件里读取该文件的路径必须精准匹配
• 检查PHP注册代码的路径：比如register_block_type( __DIR__ . '/blocks/your-block/block.json' );，路径写错会直接导致块配置加载失败

2. 检查块的注册逻辑完整性 #

• 确保PHP代码在init钩子中执行注册：

  add_action( 'init', 'register_my_custom_block' );
  function register_my_custom_block() {
      register_block_type( __DIR__ . '/blocks/your-block/block.json' );
  }
  

• 验证block.json中指定的editorScript、style等资源路径正确，且这些资源已通过wp-scripts等工具正确编译，PHP没有手动禁用资源自动加载逻辑

3. 校验block.json核心配置 #

• 检查name字段：必须是唯一的命名空间格式（如my-plugin/my-custom-block），不能和旧插件或现有块重名
• 确认apiVersion与当前WordPress版本兼容：WP 6.0+建议用3，旧版本对应2或1
• 排查是否误设hidden: true，或是category字段填写了不存在的分类（比如自定义分类未提前注册）

4. 排查JS注册问题 #

• 如果手动调用registerBlockType，要确保代码在正确的时机执行，且配置导入无误：

  import { registerBlockType } from '@wordpress/blocks';
  import metadata from './block.json';
  import Edit from './edit';
  import Save from './save';
  
  registerBlockType( metadata.name, {
      edit: Edit,
      save: Save,
  } );
  

• 打开浏览器Network面板，确认块的JS文件是否成功加载，没有404或加载失败的情况

5. 清除缓存与排除环境冲突 #

• 清空WordPress后台缓存、浏览器缓存，静态资源缓存可能导致新插件的JS/CSS未被加载
• 切换到Twenty Twenty-Four这类默认主题测试，排除主题代码的干扰
• 临时禁用其他Gutenberg相关插件，排查是否存在插件冲突

6. 验证块是否完成注册 #

• 在浏览器控制台执行以下代码，搜索你的块名称，确认是否已注册：

  console.log( wp.data.select('core/blocks').getBlockTypes().filter( block => block.name === 'my-plugin/my-custom-block' ) );
  

• 若输出为空，说明PHP注册逻辑未生效；若有结果但编辑器不显示，检查块的title、icon等配置是否完整，或是被编辑器过滤规则拦截

内容的提问来源于stack exchange，提问作者E. Jacques