WordPress Gutenberg自定义块编辑时验证失败（属性不匹配）

从错误信息来看，核心问题是编辑器解析块时预期的属性结构和save函数输出的HTML属性不匹配——你预期图片元素只有class="testimonial-image"，但实际输出的图片还带了src属性，导致属性数组长度不一致，触发验证失败。以下是具体解决步骤：

1. 规范block.json的图片属性定义 #

确保图片属性存储的是完整的媒体对象，而非单独的src值，这样编辑器能正确识别属性结构：

{
  "apiVersion": 3,
  "name": "create-block/testimonial",
  "title": "Testimonial",
  "category": "widgets",
  "attributes": {
    "testimonialImage": {
      "type": "object",
      "default": null
    },
    "name": {
      "type": "string",
      "default": ""
    },
    "position": {
      "type": "string",
      "default": ""
    },
    "testimonialText": {
      "type": "string",
      "default": "",
      "source": "html",
      "selector": "blockquote.testimonial-text"
    }
  },
  "editorScript": "file:./index.js",
  "style": "file:./style-index.css"
}

2. 修正编辑组件的图片处理逻辑 #

在edit.js中使用MediaUpload时，要完整存储选中的媒体对象，不要只提取src：

import { __ } from '@wordpress/i18n';
import { useBlockProps, MediaUpload, Button } from '@wordpress/block-editor';

export default function Edit( { attributes, setAttributes } ) {
  const blockProps = useBlockProps();

  return (
    <div { ...blockProps }>
      <MediaUpload
        onSelect={ ( media ) => {
          // 存储完整的媒体对象，包含url、alt、id等
          setAttributes( { testimonialImage: media } );
        } }
        allowedTypes={ [ 'image' ] }
        value={ attributes.testimonialImage?.id }
        render={ ( { open } ) => (
          <Button onClick={ open } variant="secondary">
            { attributes.testimonialImage ? (
              <img 
                src={ attributes.testimonialImage.url } 
                alt={ attributes.testimonialImage.alt || '' } 
                className="testimonial-image" 
              />
            ) : (
              __( '添加头像', 'testimonial' )
            ) }
          </Button>
        ) }
      />
      <input
        type="text"
        value={ attributes.name }
        onChange={ ( e ) => setAttributes( { name: e.target.value } ) }
        placeholder={ __( '姓名', 'testimonial' ) }
      />
      <input
        type="text"
        value={ attributes.position }
        onChange={ ( e ) => setAttributes( { position: e.target.value } ) }
        placeholder={ __( '职位', 'testimonial' ) }
      />
      <textarea
        value={ attributes.testimonialText }
        onChange={ ( e ) => setAttributes( { testimonialText: e.target.value } ) }
        placeholder={ __( 'Testimonial 内容', 'testimonial' ) }
      />
    </div>
  );
}

3. 对齐save函数的HTML输出 #

确保save函数输出的图片元素结构和编辑时完全一致，不要额外添加或遗漏属性：

import { useBlockProps } from '@wordpress/block-editor';

export default function save( { attributes } ) {
  const blockProps = useBlockProps.save();

  return (
    <div { ...blockProps }>
      { attributes.testimonialImage && (
        <img
          src={ attributes.testimonialImage.url }
          alt={ attributes.testimonialImage.alt || '' }
          className="testimonial-image"
        />
      ) }
      { attributes.name && <h3>{ attributes.name }</h3> }
      { attributes.position && <p className="position">{ attributes.position }</p> }
      { attributes.testimonialText && <blockquote className="testimonial-text">{ attributes.testimonialText }</blockquote> }
    </div>
  );
}

4. 清理旧数据并测试 #

如果之前已在编辑器中添加过错误的块实例，需要删除旧块并重新添加——因为数据库中已存储的错误属性结构会持续触发验证失败，重置后才能验证修复效果。

关键注意点 #

• 始终保证block.json的属性定义、edit组件的属性处理、save组件的HTML输出三者完全一致，任何一处不匹配都会触发验证错误。
• 不要将图片的src、alt拆分为单独属性存储，统一使用完整的媒体对象，这是Gutenberg块处理媒体的标准方式。

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