本教程旨在解决wordpress自定义古腾堡区块在编辑器中不显示的问题。核心原因通常在于javascript脚本的加载路径配置不正确，特别是当开发者误用文件系统路径（如`wp_plugin_dir`）而非url路径（如`plugin_dir_url(__file__)`）来注册前端资源时。文章将详细阐述正确的资源注册方法，并提供示例代码，确保您的自定义区块能顺利加载并出现在古腾堡编辑器中。
在WordPress古腾堡编辑器中开发自定义区块时，一个常见且令人困扰的问题是：尽管代码看起来都正确无误，但自定义区块却无法在区块插入器中找到。这通常表明区块的JavaScript或CSS资源未能被编辑器正确加载。本文将深入探讨这一问题，并提供详细的解决方案。
理解古腾堡区块的资源加载机制
WordPress古腾堡区块的注册和渲染涉及前端（JavaScript、CSS）和后端（PHP）的协同工作。当您通过register_block_type函数在PHP中注册一个区块时，您需要指定其编辑脚本（editor_script）和样式（editor_style），这些通常是JavaScript和CSS文件的句柄。WordPress随后会根据这些句柄去加载对应的资源。
关键在于，wp_register_script和wp_register_style等函数在注册脚本和样式时，其第二个参数期望的是一个可由浏览器访问的URL路径，而非服务器上的文件系统路径。这是因为浏览器需要通过HTTP请求来获取这些文件。
常见问题：错误的脚本路径
许多开发者在初次开发自定义区块时，可能会错误地使用文件系统路径来构建脚本的URL。例如，使用WP_PLUGIN_DIR或ABSPATH等常量来拼接资源路径。虽然这些常量可以帮助您找到服务器上的文件，但它们并不能生成一个浏览器可以访问的URL。
考虑以下错误的PHP注册代码示例：
add_action('init', function() {
$asset_file = include( WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.asset.php');
// 错误：WP_PLUGIN_DIR 提供的是文件系统路径，而非URL
wp_register_script('ghs-landing-page',
WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.js',
$asset_file['dependencies'],
$asset_file['version']);
register_block_type('ghs/landing-page-block', [
'api_version' => 2,
'editor_script' => 'ghs-landing-page',
]);
});在这段代码中，WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.js'会生成类似/var/www/html/wp-content/plugins/ghs-custom-blocks/assets/js/landing-page-block.js这样的服务器文件路径。当WordPress尝试将其作为URL传递给浏览器时，浏览器会尝试从网站的根目录加载这个路径，导致404错误，从而使区块的JavaScript逻辑无法加载，最终区块也就不会出现在编辑器中。
解决方案：使用正确的URL函数
解决此问题的核心是使用WordPress提供的函数来获取插件或主题的URL路径。对于插件，最常用的函数是plugin_dir_url(__FILE__)。这个函数会返回当前插件目录的URL，例如http://yourdomain.com/wp-content/plugins/your-plugin/。
结合此函数，我们可以构建正确的脚本URL。
1. JavaScript区块定义 (示例)
首先，确保您的JavaScript区块定义是正确的。这部分代码通常通过Webpack等工具编译。
import { registerBlockType } from '@wordpress/blocks'
registerBlockType('ghs/landing-page-block', {
title: 'Landing Page',
apiVersion: 2,
category: 'design',
icon: 'smiley',
description: 'Layout for the GHS landing page',
keywords: ['GHS', 'landing', 'page', 'front'],
edit: () => {
return (hello)
},
save: () => {
return (hello)
}
});2. PHP区块注册 (修正版)
接下来，修正PHP中的区块注册代码，使用plugin_dir_url(__FILE__)来构建脚本的URL。
add_action('init', function() {
// 获取插件基础URL
$plugin_base_url = plugin_dir_url(__FILE__);
// 假设您的资产文件在插件根目录下的 'assets/js/' 文件夹中
// 确保这里的路径与实际文件位置相符
$asset_file_path = plugin_dir_path(__FILE__) . 'assets/js/landing-page-block.asset.php';
if (file_exists($asset_file_path)) {
$asset_file = include($asset_file_path);
} else {
// 如果 .asset.php 文件不存在，设置默认依赖和版本
$asset_file = ['dependencies' => [], 'version' => filemtime(plugin_dir_path(__FILE__) . 'assets/js/landing-page-block.js')];
}
// 正确：使用 plugin_dir_url(__FILE__) 构建脚本的URL
wp_register_script(
'ghs-landing-page',
$plugin_base_url . 'assets/js/landing-page-block.js', // 正确的URL路径
$asset_file['dependencies'],
$asset_file['version']
);
register_block_type('ghs/landing-page-block', [
'api_version' => 2,
'editor_script' => 'ghs-landing-page', // 确保句柄匹配
]);
});代码说明：
- plugin_dir_url(__FILE__): 这个函数会返回当前PHP文件所在目录的URL。通过将其与脚本的相对路径拼接，我们得到了一个浏览器可以访问的完整URL。
- plugin_dir_path(__FILE__): 用于获取文件系统路径，在包含.asset.php文件时仍然适用，因为它需要文件系统路径。
- .asset.php文件：这是WordPress块开发中用于管理脚本依赖和版本号的推荐方式。确保其路径和内容正确。如果文件不存在，代码中也提供了回退方案。
额外注意事项与排查技巧
-
浏览器开发者工具：
- 网络 (Network) 标签页： 打开古腾堡编辑器，检查浏览器的网络请求。查找您的区块脚本文件（例如landing-page-block.js）。如果看到404错误，那么路径配置无疑是错误的。
- 控制台 (Console) 标签页： 检查是否有JavaScript错误。有时，即使脚本加载了，但其中的错误也可能阻止区块的注册。
- 缓存问题： 务必清除所有缓存，包括浏览器缓存、WordPress缓存插件缓存以及CDN缓存（如果使用）。缓存可能会导致旧的、错误的路径配置持续生效。
- 句柄匹配： 确保wp_register_script中定义的脚本句柄（例如'ghs-landing-page'）与register_block_type中editor_script参数的值完全匹配。
- 文件存在性： 仔细检查JavaScript文件和.asset.php文件在服务器上的实际位置，确保PHP代码中拼接的路径能够准确指向它们。
- 插件/主题冲突： 尝试切换到默认主题（如Twenty Twenty-Four），并禁用其他所有插件，只保留您的自定义区块插件，以排除潜在的冲突。
总结
自定义WordPress古腾堡区块不显示在编辑器中，最常见的原因是JavaScript脚本的加载路径配置不正确。核心在于区分文件系统路径和URL路径，并始终使用plugin_dir_url(__FILE__)（对于插件）或get_template_directory_uri()（对于主题）等函数来生成浏览器可访问的资源URL。通过仔细检查代码并利用浏览器开发者工具进行排查，您可以有效地解决此类问题，确保您的自定义区块顺利集成到WordPress编辑器中。
