文章目录
结论先行：在主题或插件目录创建 block.json 定义区块，用 register_block_type 指向构建目录，通过 theme.json 的 styles 字段隔离编辑与前端样式，再注册区块样板。站点编辑器中可拖入且前端渲染无样式错位即成功。
准备：环境与版本现状
2026 年 WordPress 核心版本为 6.8，要求 PHP 8.2+、Node 20+。创建插件目录并初始化构建工具：
mkdir wp-content/plugins/my-block && cd my-block
npm init -y
npm install @wordpress/scripts@28 --save-dev确认当前主题根目录存在 theme.json 且 version 为 3。若使用子主题，父主题需声明 block styles 支持。准备阶段未完成时切勿注册区块，否则编辑器报缺失依赖。
block.json 字段
block.json 是区块元数据标准文件，放置于插件根目录或 build/ 内。以下为最小可用字段示例：
{
"name": "my-plugin/notice",
"title": "通知区块",
"category": "design",
"icon": "warning",
"supports": { "html": false },
"style": "file:./style-index.css",
"editorScript": "file:./index.js"
}关键字段说明：
| 字段 | 作用 |
|---|---|
| name | 含命名空间，全局唯一 |
| style | 前端样式文件路径 |
| editorScript | 编辑器内 JS 入口 |
常见坑：style 路径写错导致前端无样式；name 漏写斜杠会使注册失败。验证：执行 wp @prod plugin list 确认插件已启用且无警告。
register_block_type 注册
在插件主文件 my-block.php 中调用标准函数。PHP 代码：
获取报价
邮箱 + 需求 + 预算区间，24 小时内回复报价。
<?php
function my_block_init() {
register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'my_block_init' );该函数在 2026 年仍为唯一服务端注册 API，传入包含 block.json 的目录即可。构建步骤：npm run build 生成 build/index.js 与 style-index.css。失败回退：注释注册行并切换至经典编辑器插件，数据库无改动。
区块样式与前端样式分离
编辑态样式写在区块的 editor.css，前端仅加载 style-index.css。在 theme.json 中可针对区块覆盖：
{
"version": 3,
"styles": {
"blocks": {
"my-plugin/notice": {
"color": { "background": "#f5f5f5" }
}
}
}
}分离价值：编辑器预览样式不污染前端性能，且主题换肤不影响区块结构。验证：查看前端网页源代码，应仅含 style-index.css 而不含 editor 专用类。若混淆，清除 /wp-content/uploads/theme-json 缓存。
区块样板
区块样板（Block Pattern）提升运营复用效率。在 PHP 注册：
<?php
register_block_pattern(
'my-plugin/notice-pattern',
array(
'title' => '通知样板',
'content' => '<!-- wp:my-plugin/notice --><p>示例</p><!-- /wp:my-plugin/notice -->',
)
);content 内 HTML 注释必须原样转义。若内容非法会导致编辑器白屏，回滚即临时注释该注册。也可在 theme.json 的 patterns 目录托管，但 PHP 方式更利于动态数据。
验证：如何确认区块正确加载
分步验证：1) 打开站点编辑器，左侧区块列表出现“通知区块”；2) 拖入画布，编辑器样式生效；3) 访问前端页面，样式与主题分离且布局正确；4) CLI 运行 wp block list --name=my-plugin/notice 返回元数据。任一环节缺失即未做对。
回滚：失败时的降级方案
若白屏或区块缺失：在插件页停用 my-block；生产环境使用 git revert HEAD~1 或恢复 wp-content/plugins 备份。由于仅增删静态资源与钩子，无数据库迁移，回滚安全。
常见问题
区块在编辑器不显示怎么办？
检查 block.json 的 name 命名空间与 register_block_type 路径一致，且 build/index.js 已生成。运行 npm run build 后刷新。
theme.json 修改后前端无变化？
WordPress 6.8 会缓存 theme.json 于 uploads，删除该缓存文件并硬刷新浏览器即可。
区块样板注册后搜索不到？
确认 register_block_pattern 的 title 非空，且区块已注册。在编辑器“样板”面板按标题筛选。
动作清单：
- 创建插件目录并编写 block.json 与构建脚本
- 用 register_block_type 注册 build 目录并 npm run build
- 在 theme.json 分离编辑与前端样式并清缓存
- 注册区块样板并通过编辑器与前端双验证
需要专业 WordPress 自定义区块开发？联系 我们的定制开发服务 快速落地。
“, “faq”: [ { “question”: “区块在编辑器不显示怎么办？”, “answer”: “检查 block.json 的 name 命名空间与 register_block_type 路径一致，且 build/index.js 已生成。运行 npm run build 后刷新。” }, { “question”: “theme.json 修改后前端无变化？”, “answer”: “WordPress 6.8 会缓存 theme.json 于 uploads，删除该缓存文件并硬刷新浏览器即可。” }, { “question”: “区块样板注册后搜索不到？”, “answer”: “确认 register_block_pattern 的 title 非空，且区块已注册。在编辑器“样板”面板按标题筛选。” } ], “cover”: “Flat technical illustration showing modular block components linking to a website layout, soft gradient colors, minimal geometric shapes representing code and design separation, clean modern vector style, no text or symbols.