自定义WordPress Block移入admin文件夹后无法显示问题排查

问题 #

我用WordPress Boilerplate开发了一个插件，所有后台定制内容都放在admin文件夹中。创建了一个自定义Block，作为独立插件时一切正常，但集成到现有插件的admin文件夹后无法正常工作。

Block已成功注册（路径错误时会报错，且在已注册Block列表中能找到它），但无法在侧边栏显示。

注册代码（admin文件夹内的PHP文件，通过init钩子调用） #

if (function_exists('wp_register_block_types_from_metadata_collection')) {
    wp_register_block_types_from_metadata_collection(__DIR__ . '/my-block/build', __DIR__ . '/my-block/build/blocks-manifest.php');
    return;
}

manifest/block.json内容 #

<?php
// This file is generated. Do not modify it manually.
return array(
    'my-plugin' => array(
        '$schema' => 'https://schemas.wp.org/trunk/block.json',
        'apiVersion' => 3,
        'name' => 'my-plugin/my-plugin',
        'version' => '0.1.0',
        'title' => 'Awards',
        'category' => 'widgets',
        'icon' => 'awards',
        'description' => 'Custom Fields for Awards',
        'example' => array(
            
        ),
        'supports' => array(
            'html' => false
        ),
        'textdomain' => 'my-plugin',
        'editorScript' => 'file:./index.js',
        'editorStyle' => 'file:./index.css',
        'style' => 'file:./style-index.css',
        'render' => 'file:./render.php',
        'viewScript' => 'file:./view.js'
    )
);

index.js内容 #

import { registerBlockType } from '@wordpress/blocks';

import { registerPlugin } from '@wordpress/plugins';

import MetaBox from './components/MetaBox';

import './style.scss';


import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata.name, {
    edit: Edit,
} );

registerPlugin( 'my-block', {
    render: MetaBox
} );

排查方向与解决方案 #

1. 脚本/样式路径解析错误 #

WordPress解析file:开头的路径时，是以插件根目录为基准，而非admin子目录。原block.json中的相对路径在插件结构变化后会失效，导致资源加载失败。

• 解决：修改block.json中的路径，例如将file:./index.js改为file:./admin/my-block/build/index.js，确保指向正确的文件位置。
• 验证：打开浏览器开发者工具，查看控制台是否有404错误，或在“网络”标签页检查index.js是否成功加载。

2. 钩子执行时机错误 #

如果用init钩子注册Block，可能在编辑器核心依赖（如@wordpress/blocks）加载前执行，导致脚本失效。

• 解决：将注册代码的钩子改为enqueue_block_editor_assets，这个钩子专为编辑器资源加载设计，能确保依赖就绪。
• 修改示例：

add_action('enqueue_block_editor_assets', function() {
    if (function_exists('wp_register_block_types_from_metadata_collection')) {
        wp_register_block_types_from_metadata_collection(__DIR__ . '/my-block/build', __DIR__ . '/my-block/build/blocks-manifest.php');
    }
});

3. 权限与条件加载冲突 #

插件中可能存在仅在特定后台页面加载admin目录代码的逻辑（如is_admin()的判断），导致编辑器页面未触发Block注册。

• 解决：检查插件的加载逻辑，确保post.php、post-new.php等编辑器页面能执行Block注册代码。
• 验证：在注册代码前添加error_log('Block registered');，查看WordPress debug.log确认代码是否在编辑器页面执行。

4. 命名冲突 #

index.js中registerPlugin的名称my-block可能与现有插件/Block冲突，导致侧边栏组件无法渲染。

• 解决：修改插件注册名称为唯一值，例如my-plugin-awards-meta-box。
• 修改示例：

registerPlugin( 'my-plugin-awards-meta-box', {
    render: MetaBox
} );

5. 构建产物路径错误 #

Block构建时的输出目录结构或blocks-manifest.php中的路径未同步更新，也会导致资源加载失败。

• 解决：重新构建Block，确保build目录生成在admin/my-block/下，且blocks-manifest.php中的路径引用正确。

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