WordPress编辑古腾堡块报Unexpected token '<'错误排查

错误根因 #

• 你编写的JS代码使用了JSX语法（即<Fragment>、<BlockEdit>这类尖括号标签），原生浏览器无法直接识别JSX，加载时会将尖括号判定为HTML标签起始符，直接抛出Uncaught SyntaxError: Unexpected token '<'错误
• 脚本注册时依赖声明不全，缺少Gutenberg编辑器运行自定义扩展所需的核心依赖包，即使语法正确也会出现依赖未定义的报错
• 现有代码仅实现了编辑器侧的属性注册和控件添加，缺少保存块时追加自定义类名、前端样式适配的逻辑，无法实现最终的移动端滚动效果
• 额外常见触发场景：自定义JS文件路径配置错误，服务器返回404 HTML页面而非JS内容，HTML内容开头的<!DOCTYPE html>或<html>标签的<字符也会触发完全相同的语法错误

分步修复方案 #

1. 修正PHP侧脚本注册逻辑 #

替换原有的脚本注册代码，补全所有必需依赖，添加文件版本号避免缓存干扰：

function my_editor_enqueue() {
    wp_enqueue_script(
        'my-gutenberg-filters',
        get_template_directory_uri() . '/js/filters.js',
        // 补全Gutenberg扩展必需的依赖
        ['wp-blocks', 'wp-hooks', 'wp-compose', 'wp-components', 'wp-block-editor', 'wp-element'],
        // 用文件修改时间作为版本号，避免代码更新后浏览器加载旧缓存
        filemtime(get_template_directory() . '/js/filters.js'),
        true
    );
}
add_action( 'enqueue_block_editor_assets', 'my_editor_enqueue' );

2. 替换自定义JS代码（无需构建工具，浏览器可直接运行） #

去掉所有JSX语法，改用Gutenberg内置的createElement方法编写逻辑，同时补充块保存时追加滚动类名的逻辑，将原有filters.js内容替换为以下代码：

const el = wp.element.createElement;
const { Fragment } = wp.element;
const { ToggleControl } = wp.components;
const { InspectorAdvancedControls } = wp.blockEditor;
const { addFilter } = wp.hooks;

// 给核心表格块注册自定义属性，扩展保存逻辑
function addScrollableTableSetting(settings, name) {
    if (name !== 'core/table') return settings;

    // 注册滚动开关属性
    settings.attributes = Object.assign({}, settings.attributes, {
        scrollable: {
            type: 'boolean',
            default: false
        }
    });

    // 重写保存逻辑，开启开关时给表格容器追加自定义类名
    const originalSave = settings.save;
    settings.save = function(props) {
        const saveElement = originalSave(props);
        if (!saveElement || !props.attributes.scrollable) return saveElement;
        
        const existingClass = saveElement.props.className || '';
        saveElement.props.className = `${existingClass} is-scrollable-table`.trim();
        return saveElement;
    };

    return settings;
}
addFilter(
    'blocks.registerBlockType',
    'scrollable-table/register-setting',
    addScrollableTableSetting
);

// 编辑器侧边栏添加开关控件
const addScrollableToggleControl = wp.compose.createHigherOrderComponent((BlockEdit) => {
    return (props) => {
        // 非表格块直接返回原编辑组件
        if (props.name !== 'core/table') {
            return el(BlockEdit, props);
        }

        return el(
            Fragment,
            null,
            el(BlockEdit, props),
            // 选中表格块时，在高级设置面板显示开关
            props.isSelected && el(
                InspectorAdvancedControls,
                null,
                el(ToggleControl, {
                    label: '移动端横向滚动适配',
                    checked: !!props.attributes.scrollable,
                    onChange: () => props.setAttributes({ scrollable: !props.attributes.scrollable })
                })
            )
        );
    };
}, 'addScrollableToggleControl');
addFilter(
    'editor.BlockEdit',
    'scrollable-table/add-toggle-control',
    addScrollableToggleControl
);

3. 添加前端适配样式 #

将以下CSS加入主题全局样式文件，实现开启开关后表格的移动端横向滚动效果：

.is-scrollable-table {
    max-width: 100%;
    overflow-x: auto;
    -webkit-overflow-scrolling: touch;
}
.is-scrollable-table table {
    min-width: 640px; /* 可根据自身表格内容的最小宽度调整 */
    margin: 0;
}

排查校验要点 #

• 修改代码后先在浏览器开发者工具的Network面板找到filters.js请求，确认响应状态为200，响应内容是JS代码而非404/500的HTML页面
• 若使用缓存插件/CDN，更新代码后需要清空缓存，避免加载旧版本的错误文件
• 如果后续需要使用JSX语法提升开发效率，需要配置WordPress官方的构建工具将JSX编译为原生JS后再加载，不能直接将含JSX的源文件作为前端脚本引入

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