解决WordPress自定义古腾堡区块不显示问题：脚本路径配置详解

本教程旨在解决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/。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

22

查看详情

结合此函数，我们可以构建正确的脚本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 (<div>hello</div>)
    },
    save: () => {
        return (<div>hello</div>)
    }
});

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块开发中用于管理脚本依赖和版本号的推荐方式。确保其路径和内容正确。如果文件不存在，代码中也提供了回退方案。

额外注意事项与排查技巧

1. 浏览器开发者工具：
   • 网络 (Network) 标签页： 打开古腾堡编辑器，检查浏览器的网络请求。查找您的区块脚本文件（例如landing-page-block.js）。如果看到404错误，那么路径配置无疑是错误的。
   • 控制台 (Console) 标签页： 检查是否有JavaScript错误。有时，即使脚本加载了，但其中的错误也可能阻止区块的注册。
2. 缓存问题： 务必清除所有缓存，包括浏览器缓存、WordPress缓存插件缓存以及CDN缓存（如果使用）。缓存可能会导致旧的、错误的路径配置持续生效。
3. 句柄匹配： 确保wp_register_script中定义的脚本句柄（例如'ghs-landing-page'）与register_block_type中editor_script参数的值完全匹配。
4. 文件存在性： 仔细检查JavaScript文件和.asset.php文件在服务器上的实际位置，确保PHP代码中拼接的路径能够准确指向它们。
5. 插件/主题冲突： 尝试切换到默认主题（如Twenty Twenty-Four），并禁用其他所有插件，只保留您的自定义区块插件，以排除潜在的冲突。

总结

自定义WordPress古腾堡区块不显示在编辑器中，最常见的原因是JavaScript脚本的加载路径配置不正确。核心在于区分文件系统路径和URL路径，并始终使用plugin_dir_url(__FILE__)（对于插件）或get_template_directory_uri()（对于主题）等函数来生成浏览器可访问的资源URL。通过仔细检查代码并利用浏览器开发者工具进行排查，您可以有效地解决此类问题，确保您的自定义区块顺利集成到WordPress编辑器中。

以上就是解决WordPress自定义古腾堡区块不显示问题：脚本路径配置详解的详细内容，更多请关注php中文网其它相关文章！