WordPress 区块开发怎么做：跟着官方教程构建第一个 block 的踩坑笔记（Bricks 教程）

背景与前置知识

作为一名最近刚学了些 JavaScript（来自这里）和 React（来自这里）的人，以下是我跟着官方教程创建第一个 WordPress block 时的思考与笔记。

• 如果能提前说明看懂这段代码需要 JavaScript 和 React 基础就好了。
• scaffold = 搭建初始结构（脚手架）。
• 新建一个名为 “Block Tutorial” 的文件夹 ← 实际上不用这么做，因为 npx 命令会在 plugins 目录下自动生成名为 copyright-date-block 的插件文件夹。

搭建插件与修复致命错误

在 Local 里新建了一个站点，在 Terminal 中打开 plugins 目录并运行了

npx @wordpress/create-block@latest copyright-date-block --variant=dynamic
cd copyright-date-block

出现了这个错误：

AI 的回复：

好吧，看来没什么好担心的——我当初是这么想的……

激活插件后：

在谷歌上搜了半小时、试了一堆办法（包括重装 Node）之后，在这里找到了修复方法：

export NODE_ENV=development

重新运行了

npx @wordpress/create-block@latest copyright-date-block --variant=dynamic

这一次：

看起来没问题了吧？可是，那个致命错误依然在出现。

在折腾了 45 分钟、试了一堆办法之后，找到了这个修复方法：

在插件目录下：

mkdir -p dir

在 package.json 中，把

"build": "wp-scripts build --webpack-copy-php --blocks-manifest",

替换为

"build": "wp-scripts build --webpack-copy-php && wp-scripts build-blocks-manifest && cp build/blocks-manifest.php dir/",

再把

"start": "wp-scripts start --webpack-copy-php --blocks-manifest"

替换为

"start": "wp-scripts start --webpack-copy-php && wp-scripts build-blocks-manifest && cp build/blocks-manifest.php dir/"

在 copyright-date-block.php 中，把

$manifest_data = require __DIR__ . '/build/blocks-manifest.php';

改为

$manifest_data = require __DIR__ . '/dir/blocks-manifest.php';

运行

npm run build

这应该能修复由于缺少 blocks-manifest.php 文件而导致的致命错误。

现在你可以

npm run start

via

回到官方教程：构建动态区块

好。是时候回到官方教程了。

生成的 index.js 里有

import { registerBlockType } from '@wordpress/blocks';

我在 node_modules/@wordpress 里找不到 blocks 文件夹。它本应该在这里吗？搜索 registerBlockType，我也找不到它的定义在哪里。

同样地，另外几个包也缺失了。

通过运行下面的命令修复：

npm install @wordpress/blocks @wordpress/block-editor @wordpress/components @wordpress/i18n @wordpress/element --save

如果不做上面的操作，像设置自定义日历图标这样的修改，在编辑器里不会生效。

import Edit from './edit';

这里我们正在导入 Edit 组件。

import metadata from './block.json';

metadata 是一个本地变量（一个对象），指向 block.json 里的 JSON 数据。我们也可以把它命名为别的，比如 blockdata。

在 edit.js 中：

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

export default function Edit() {
	const currentYear = new Date().getFullYear().toString();

	return <p {...useBlockProps()}>© {currentYear}</p>;
}

记住：除非 npm run start 正在运行，否则对文件的修改不会生效。

在添加

console.log(attributes);

到 Edit() 中之后，我打开控制台，却看到一个空对象。原本期望看到的是一个包含 showStartingYear 和 startingYear 这两个键的对象。不太确定原因。

关于 __nextHasNoMarginBottom 和 __next40pxDefaultSize：

value={startingYear || ""}

的意思是

• 如果 startingYear 存在且为真值（truthy），就使用它的值
• 如果 startingYear 为假值（undefined、null、空字符串、0、false 等），就改用一个空字符串（“”）

onChange={(value) => setAttributes({ startingYear: value })}

为什么我们要把 startingYear 这个 state 更新成一个只包含 startingYear 键的对象？难道我们不应该是先解构（destructure）原始对象、再替换其中的 startingYear 键吗？那 showStartingYear 键怎么办？

AI 的回答：

看起来，动态变体（dynamic variant）的区块创建是这样工作的：

• 在 block.json 中，我们设置区块「支持」哪些功能：这些是设计相关的设置。例如：文字和背景颜色、字体排印设置（如 font-size）。
• 在 block.json 中，我们设置 attributes（状态变量）。这些是用户可以为区块修改的配置项，它们会影响最终输出。
• 在 edit.js（负责区块编辑器中的输出）里，我们添加一个自定义设置面板，并在其中放置控件（本例中是文本输入框和开关 toggle）。用户在输入控件中填的值会更新对应的 state。开关控件是否被勾选，也会与对应的 state 同步。只有当开关被勾选时，我们才会渲染文本（输入）控件。
• 对于前端输出，我们编辑 render.php。$attributes 数组以属性名作为键（keys）。

静态区块

<p { ...useBlockProps.save() }>

useBlockProps.save()：

它返回一个对象。

save.js 里的函数名应该是 Save() 而不是 save()，因为它是一个 React 组件。

不太确定为什么

export default function Save() {
	return (
		<p {...useBlockProps.save()}>
			{"Copyright Date Block – hello from the saved content!"}
		</p>
	);
}

不直接写成

export default function Save() {
	return (
		<p {...useBlockProps.save()}>
			Copyright Date Block – hello from the saved content!
		</p>
	);
}

这里涉及的东西太多了，我也不确定为了做一个静态区块，折腾这些到底值不值得。我先跳过这部分，等以后需要时再回来研究。

小结

本文记录了作者从零跟着官方教程构建第一个 WordPress block 的完整过程与踩坑：先用 npx @wordpress/create-block 脚手架生成插件，遇到 blocks-manifest.php 缺失导致的致命错误，并通过调整 package.json 脚本与 copyright-date-block.php 中的 manifest 路径修复；随后补齐缺失的 @wordpress/* 依赖包，逐步实现动态区块的 edit.js、属性（attributes）与 state 同步；最后简要对比了静态区块 save.js 的写法。整体偏向「边学边记」的笔记风格，适合刚接触 WordPress 区块开发、同时也在用 Bricks 的开发者参考。

相关阅读

• WordPress 页面构建器横评 2026——Bricks 凭什么还是排第一
• Bricks Container 与 Flexbox 布局入门：建站最该先搞懂的一课
• Bricks Builder 画布是什么——第一次进编辑器别懵的界面速览

站长

Ray Chan

WordPress Developer & Bricks Specialist

WordPress developer with 10+ years of client builds. Switched to Bricks in 2023 — now builds fast WordPress sites and migrates legacy Elementor/Divi projects.

获取报价 →浏览全部教程