本文深入探讨wordpress自定义区块在编辑器中不显示的问题，揭示常见原因在于javascript资源路径配置不当。教程将详细解释为何使用文件系统路径（如wp_plugin_dir）而非url路径会导致区块加载失败，并提供使用plugin_dir_url(__file__)的正确注册方法及最佳实践，确保您的自定义区块能顺利集成并正常工作。
理解WordPress自定义区块的构成
WordPress的Gutenberg编辑器引入了区块（Blocks）的概念，极大地提升了内容编辑的灵活性。一个自定义区块通常由两部分组成：
PHP注册文件：在服务器端注册区块，定义其元数据（如名称、类别、图标）以及加载其JavaScript和CSS资源。JavaScript定义文件：在客户端定义区块的编辑界面（edit函数）和保存内容（save函数）。
当自定义区块在编辑器中无法显示时，通常是由于PHP注册过程中对JavaScript资源的处理不当。
常见问题：区块未在编辑器中显示
许多开发者在创建自定义区块时会遇到一个令人沮丧的问题：区块代码似乎都已正确编写，但它就是不在Gutenberg编辑器的区块插入器中出现。经过一系列排查，例如确认插件正常工作、尝试不同钩子、检查文件路径、甚至切换到默认主题，问题依然存在。
让我们来看一个典型的PHP注册代码片段，它可能导致这种问题：
add_action('init', function() { $asset_file = include( WP_PLUGIN_DIR . '/ghs-custom-blocks/assets/js/landing-page-block.asset.php'); 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', ]);});
以及对应的JavaScript区块定义（通常不是问题的直接原因）：
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) }});
问题根源：文件系统路径与URL路径的混淆
上述PHP代码中的关键错误在于wp_register_script函数的第二个参数。wp_register_script期望的是一个可公开访问的URL，指向你的JavaScript文件。然而，WP_PLUGIN_DIR常量返回的是插件目录的文件系统路径（例如 /var/www/html/wp-content/plugins/your-plugin-name），而不是其对应的Web URL。
当WordPress尝试加载WP_PLUGIN_DIR . ‘/ghs-custom-blocks/assets/js/landing-page-block.js’作为脚本URL时，它会生成一个类似file:///var/www/html/wp-content/plugins/ghs-custom-blocks/assets/js/landing-page-block.js的路径，或者直接尝试从网站根目录寻找一个名为/var/www/html/wp-content/plugins/ghs-custom-blocks/assets/js/landing-page-block.js的文件。这显然不是一个有效的HTTP/HTTPS URL，因此浏览器无法找到并加载该脚本，导致区块无法在编辑器中注册和显示。
解决方案：使用 plugin_dir_url(__FILE__) 获取正确URL
要解决这个问题，我们需要使用WordPress提供的辅助函数来获取插件目录的正确URL。plugin_dir_url(__FILE__)是一个非常实用的函数，它返回当前文件所在插件目录的URL。
将错误的WP_PLUGIN_DIR替换为plugin_dir_url(__FILE__)，并拼接上相对路径，即可生成正确的脚本URL。
以下是修正后的PHP注册代码：
add_action('init', function() { // 确保 asset.php 文件路径正确，它通常由构建工具生成 $asset_file = include( plugin_dir_path(__FILE__) . 'assets/js/landing-page-block.asset.php'); wp_register_script( 'ghs-landing-page', // ✅ 使用 plugin_dir_url(__FILE__) 获取插件URL plugin_dir_url(__FILE__) . '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', ]);});
解释：
plugin_dir_path(__FILE__)：用于获取当前文件所在插件目录的文件系统路径。这个在include asset.php文件时是正确的，因为include需要的是文件系统路径。plugin_dir_url(__FILE__)：用于获取当前文件所在插件目录的URL。这个在wp_register_script中是必须的，因为它需要一个可供浏览器访问的Web地址。
通过这种方式，wp_register_script将获得一个有效的URL（例如 http://yourdomain.com/wp-content/plugins/ghs-custom-blocks/assets/js/landing-page-block.js），浏览器就能正确加载JavaScript文件，从而使自定义区块在Gutenberg编辑器中正常显示。
注意事项与最佳实践
区分路径类型：在WordPress开发中，始终要明确你是在处理文件系统路径（如WP_PLUGIN_DIR、plugin_dir_path()）还是URL（如plugin_dir_url()、get_template_directory_uri()）。混淆这两者是导致许多加载问题的常见原因。__FILE__ 魔术常量：__FILE__常量始终指向当前文件的完整文件系统路径。它是plugin_dir_path()和plugin_dir_url()函数正确工作的基础。调试网络请求：如果区块仍然不显示，打开浏览器的开发者工具（通常是F12），检查“网络”（Network）选项卡。刷新编辑器页面，查找是否有针对你的JavaScript文件的404错误或其他加载失败的请求。这将直接告诉你WordPress尝试从哪个URL加载脚本，从而帮助你进一步排查路径问题。asset.php 文件：现代WordPress区块开发通常使用@wordpress/scripts等工具进行构建。这些工具会自动生成一个.asset.php文件，其中包含脚本的依赖项和版本号。确保这个文件被正确include，并且它的内容是有效的。缓存问题：在开发过程中，浏览器缓存、WordPress对象缓存或CDN缓存可能会导致你更改代码后看不到立即的效果。在排查问题时，尝试清除所有相关缓存。
总结
自定义WordPress区块未在编辑器中显示的问题，通常归结为JavaScript资源加载路径的配置错误。核心在于wp_register_script函数需要一个可访问的Web URL，而非服务器上的文件系统路径。通过正确使用plugin_dir_url(__FILE__)函数，开发者可以确保脚本被正确加载，从而使自定义区块顺利集成到Gutenberg编辑器中。理解并区分文件系统路径和URL在WordPress开发中至关重要，是避免此类常见问题的关键。
以上就是WordPress自定义区块未显示：路径配置错误及解决方案的详细内容，更多请关注php中文网其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/1330888.html
微信扫一扫 
支付宝扫一扫 
