WordPress Gutenberg自定义块渲染失败，发布后页面崩溃求助

问题概述 #

• 背景：长期开发Angular 2+，无React经验，正在将Short-Code迁移为Gutenberg块，通过npx @wordpress/create-block give-camp-blocks-plugin初始化项目
• 症状：
  • 可视化编辑器正常，HTML结构正确
  • 切换到代码编辑器仅显示空块注释：<!-- wp:create-block/give-camp-blocks-plugin /-->
  • 发布后页面完全崩溃（标题、侧边栏等无法加载）
• 触发报错：

  TypeError: object null is not iterable (cannot read property Symbol(Symbol.iterator))
      at Function.from (<anonymous>)
      at l (http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:2:19718)
      at Object.__unstableMarkListeningStores (http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:2:20176)
      at http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:9:2223
      at p (http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:9:2121)
      at http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:9:2214
      at $e (http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:9:2643)
      at Be (http://localhost:9139/wp-includes/js/dist/data.min.js?ver=90cebfec01d1a3f0368e:9:2964)
      at hs (http://localhost:9139/wp-includes/js/dist/editor.min.js?ver=f49ef02c2dddb31edd0e:19:124768)
      at kt (http://localhost:9139/wp-includes/js/dist/vendor/react-dom.min.js?ver=18.2.0:10:47633)
  

当前代码实现 #

块注册文件 #

const { __ } = wp.i18n;
import metadata from './block.json';
import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText } from '@wordpress/block-editor';

registerBlockType( metadata.name, {
  apiVersion: metadata.apiVersion,
  title: metadata.title,

  edit: ( { attributes, setAttributes } ) => {
    const { content } = attributes;
    const blockProps = useBlockProps( { className: "gc-marquee" } );
    blockProps['role'] = 'marquee';
    blockProps['aria-label'] = __(content);

    return (
      <>
        <div { ...blockProps }>
          <RichText
            className="gc-scrollingtext"
            aria-hidden="true"
            tagName="p"
            placeholder={ 'Write text here ...' }
            value={ content }
            onChange={ ( value ) => setAttributes( { content: value } ) }
          />
        </div>
      </>
    );
  },

  save: ( { attributes } ) => {
    const { content } = attributes;
    const blockProps = useBlockProps.save( { className: "gc-marquee" } );
    blockProps['role'] = 'marquee';
    blockProps['aria-label'] = __(content);

    return (
      <>
        <div { ...blockProps }>
          <RichText.Content
            className="gc-scrollingtext"
            aria-hidden="true"
            tagName="p"
            value={ content }
          />
        </div>
      </>
    );
  },
} );

block.json 片段 #

{
    ...
    "attributes": {
        "content":  {
            "type": "string",
            "source": "html",
            "selector": "p",
            "default": ""
        }
    },
    ...
}

修复方案 #

1. 解决空值导致的ARIA属性异常 #

当content为空时，__(content)返回空字符串，Gutenberg处理空ARIA属性时会触发迭代空对象的错误。修改逻辑，仅在内容非空时设置aria-label：

// edit函数中
const blockProps = useBlockProps( { className: "gc-marquee" } );
blockProps['role'] = 'marquee';
if (content) {
  blockProps['aria-label'] = __(content);
}

// save函数中
const blockProps = useBlockProps.save( { className: "gc-marquee" } );
blockProps['role'] = 'marquee';
if (content) {
  blockProps['aria-label'] = __(content);
}

2. 移除不必要的React片段包裹 #

块返回单个<div>元素，无需使用React片段（<>...</>），这会干扰Gutenberg的块序列化逻辑：

// edit函数返回修改为
return (
  <div { ...blockProps }>
    <RichText
      className="gc-scrollingtext"
      aria-hidden="true"
      tagName="p"
      placeholder={ 'Write text here ...' }
      value={ content }
      onChange={ ( value ) => setAttributes( { content: value } ) }
    />
  </div>
);

// save函数返回修改为
return (
  <div { ...blockProps }>
    <RichText.Content
      className="gc-scrollingtext"
      aria-hidden="true"
      tagName="p"
      value={ content }
    />
  </div>
);

3. 修正block.json语法错误 #

检查并修正block.json中的语法问题（比如你提供的片段中"content"键值对后多余的空格），确保apiVersion设置为3（当前Gutenberg推荐版本）。

4. 重建并清除缓存 #

• 执行npm run build重新编译块代码
• 清空WordPress后台缓存和浏览器缓存，重新加载编辑器

验证 #

应用修改后：

1. 新增块并输入内容，切换到代码编辑器应能看到包含属性的块标记
2. 发布页面后刷新，页面应正常显示所有元素

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