使用@wordpress/create-block创建的插件未显示在Gutenberg编辑器中

WordPress及环境版本 #

• PHP: 8.2.10
• 数据库: MySQL 8.0.16
• WordPress版本: 6.5.3
• Node.js版本: v20.14.0
• npm版本: 10.7.0

网站通过Local工具搭建。

插件创建过程 #

在wp-content/plugins目录下执行以下命令创建custom-plugin插件：

plugins$ npx @wordpress/create-block custom-plugin

Creating a new WordPress plugin in the custom-plugin directory.

//...

Done: WordPress plugin Custom Plugin bootstrapped in the custom-plugin directory.

You can run several commands inside:

  $ npm start
    Starts the build for development.

 //...

To enter the directory type:

  $ cd custom-plugin

You can start development with:

  $ npm start

Code is Poetry
plugins$ 

后台插件状态 #

插件已成功激活，在wp-admin后台面板中可见：

问题现象 #

激活插件后，在Gutenberg编辑器中无法找到该自定义块：

有没有人遇到过同样的问题？

npm start编译日志 #

custom-plugin npm start

> custom-plugin@0.1.0 start
> wp-scripts start

assets by chunk 17.3 KiB (name: index)
  assets by path *.css 1.83 KiB
    asset index.css 957 bytes [emitted] (name: index) 1 related asset
    asset index-rtl.css 920 bytes [emitted] (name: index)
  asset index.js 15.3 KiB [emitted] (name: index) 1 related asset
  asset index.asset.php 146 bytes [emitted] (name: index)
assets by path ./*.css 1.95 KiB
  asset ./style-index.css 1020 bytes [emitted] (name: ./style-index) (id hint: style) 1 related asset
  asset ./style-index-rtl.css 979 bytes [emitted] (name: ./style-index) (id hint: style)
assets by chunk 1.07 KiB (name: view)
  asset view.js 1010 bytes [emitted] (name: view) 1 related asset
  asset view.asset.php 84 bytes [emitted] (name: view)
asset block.json 515 bytes [emitted] [from: src/block.json] [copied]
Entrypoint view 1.07 KiB (1.14 KiB) = view.js 1010 bytes view.asset.php 84 bytes 1 auxiliary asset
Entrypoint index 19.3 KiB (11.8 KiB) = 6 assets 3 auxiliary assets
runtime modules 5.17 KiB 14 modules
orphan modules 4.83 KiB [orphan] 4 modules
built modules 4.58 KiB (javascript) 474 bytes (css/mini-extract) [built]
  javascript modules 4.13 KiB
    cacheable modules 3.97 KiB
      modules by path ./src/*.js 3.87 KiB 4 modules
      modules by path ./src/*.scss 100 bytes 2 modules
    external ["wp","blocks"] 42 bytes [built] [code generated]
    external ["wp","i18n"] 42 bytes [built] [code generated]
    external ["wp","blockEditor"] 42 bytes [built] [code generated]
    external "ReactJSXRuntime" 42 bytes [built] [code generated]
  css modules 474 bytes
    css ./node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[4].use[1]!./node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[4].use[2]!./node_modules/sass-loader/dist/cjs.js??ruleSet[1].rules[4].use[3]!./src/style.scss 268 bytes [built] [code generated]
    css ./node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[4].use[1]!./node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[4].use[2]!./node_modules/sass-loader/dist/cjs.js??ruleSet[1].rules[4].use[3]!./src/editor.scss 206 bytes [built] [code generated]
  ./src/block.json 455 bytes [built] [code generated]
webpack 5.91.0 compiled successfully in 555 ms

解决步骤 #

1. 校验block.json配置
   打开custom-plugin/src/block.json，确认关键字段：

   • apiVersion：需与WordPress版本匹配（WP 6.5.3对应apiVersion 3）
   • category：使用Gutenberg默认分类（如widgets、text），若自定义分类需提前注册
   • title/description：不可为空，否则编辑器会忽略该块
   • editorScript：路径需指向编译后的文件，通常为file:./index.js

2. 确认编译产物存在
   检查custom-plugin/build目录是否生成了index.js、style-index.css等文件。若缺失，执行npm run build生成生产环境构建产物（npm start为开发模式，部分场景下不会自动生成完整build目录）。

3. 清除各类缓存

   • 关闭并重启Local工具，刷新WordPress后台
   • 清除浏览器缓存，或用无痕模式打开编辑器
   • 进入WP后台设置→固定链接，点击“保存更改”刷新重写规则

4. 检查块注册代码
   打开custom-plugin/custom-plugin.php，确认块注册代码正确：

   function create_block_custom_plugin_block_init() {
     register_block_type( __DIR__ . '/build' );
   }
   add_action( 'init', 'create_block_custom_plugin_block_init' );
   

   确保register_block_type指向的是build目录，而非src目录。

5. 排查浏览器控制台错误
   打开编辑器页面的开发者工具（F12），查看Console标签下的JavaScript错误。脚本加载失败、依赖缺失等问题都会导致块无法显示。

6. 确认用户权限
   确保当前登录用户拥有edit_posts权限，且未被插件或角色设置限制使用自定义块。

内容的提问来源于stack exchange，提问作者kawa