wordpress搭建块

完善版：WordPress 古腾堡区块从零搭建教程（含命令+参数+避坑+结构规范）

我已完整修正、补充、优化 你原文的所有内容，修正了目录错误、参数误区、流程漏洞，新增新手必看的目录结构、注册分类、运行编译、主题集成等关键步骤，直接可作为正式教程使用，逻辑更顺、更专业、零歧义。

---

搭建 WordPress 古腾堡区块：完整流程 + 命令参数详解

本教程严格遵循 WordPress 官方文档 标准流程，适合新手从零搭建自定义古腾堡区块，包含命令使用、参数含义、目录规范、避坑要点与后续开发流程。

官方教程参考：

https://developer.wordpress.org/block-editor/getting-started/tutorial/

---

一、前置说明

@wordpress/create-block 是 WordPress 官方脚手架，可一键生成标准区块代码（block.json、编辑/保存逻辑、样式等）。

有两种使用场景：

1. 生成独立插件（默认）：包含插件入口文件，可直接上传启用
2. 生成主题内区块（推荐）：不生成插件，直接集成到当前主题

---

二、首次创建区块（生成基础环境）

如果你是项目第一次创建区块 ，执行以下命令，会自动生成：
package.json、node_modules 依赖、编译脚本、区块目录

npx @wordpress/create-block@latest case-study --namespace source-block --category source-block --textdomain source-block

⚠️ 目录结构说明（修正你原文的错误）

默认不加 --no-plugin 时，生成结构如下【以下是我复制出来的结构也是正确的结构】（不是多层嵌套错误，是插件结构）：

case-study/
├─ src/           # 区块源码（核心）
├─ case-study.php # 插件入口文件
├─ block.json
├─ package.json

你看到的多层嵌套 source-block/src/case-study/src/case-study，是执行命令时目录位置不对导致的 ，不是工具问题。

✅ 正确做法：

在主题根目录执行命令，直接生成干净结构，无需复制替换。

---

三、完整命令 + 逐参数详解

npx @wordpress/create-block@latest case-study --namespace source-block --category source-block --textdomain source-block

1. npx

• Node.js 自带工具
• 无需全局安装，直接临时运行 npm 包
• 干净无残留，推荐始终使用

2. @wordpress/create-block@latest

• WordPress 官方区块脚手架
• @latest：强制使用最新版，保证兼容性
• 自动生成：区块配置、编辑界面、前端输出、样式文件

3. case-study（必填：区块名称）

• 区块文件夹名称
• 区块唯一标识的一部分
• 必须：小写英文、短横线分隔、无空格无中文
• 生成目录：./case-study/

4. --namespace source-block（命名空间 · 必须）

• 作用：给区块加前缀，避免与其他插件/主题重名
• 最终区块名称格式：命名空间/区块名
• 本例最终：source-block/case-study
• 规范：小写、短横线、无特殊符号

5. --category source-block（编辑器分类）

• 控制区块在古腾堡编辑器左侧显示在哪个分类面板

• 官方内置分类：

  • text（文本）
  • media（媒体）
  • design（设计）
  • widgets（小工具）
  • embed（嵌入）

• ⚠️ 重要：
  自定义分类必须手动注册，否则区块会自动放到「通用(Common)」分类下。

6. --textdomain source-block（翻译文本域）

• 用于 WordPress 多语言翻译（i18n 国际化）
• 一般与主题名 / 插件名保持一致
• 不做翻译也可正常使用，不影响功能

---

四、生成后的核心配置（block.json）

命令执行后，自动生成的区块标识如下：

"name": "source-block/case-study",
"title": "Case Study",
"category": "source-block",
"textdomain": "source-block"

---

五、后续创建区块（推荐：主题内开发）

当项目已有 package.json 后，必须加 --no-plugin，只生成区块源码，不生成插件入口，完美适配主题内开发。

npx @wordpress/create-block@latest card-guides-comment --no-plugin --namespace source-block --category source-block --textdomain source-block

--no-plugin 作用

• 不生成插件入口 .php 文件
• 不生成插件结构
• 只输出区块源码（干净、轻量）
• 主题集成区块的标准用法

---

六、必须补充：新手必做 3 步（原文缺失）

1. 编译区块（必须运行）

区块是 React 编写，需要编译才能使用：

npm run build

开发模式（热更新）：

npm start

2. 注册自定义分类（否则不显示）

在主题 functions.php 中添加：

add_filter( 'block_categories_all', function( $categories ) {
    return array_merge(
        $categories,
        [
            [
                'slug'  => 'source-block',
                'title' => '自定义区块',
                'icon'  => 'screenoptions',
            ],
        ]
    );
} );

3. 主题中加载区块

add_action( 'init', function() {
    register_block_type( get_stylesheet_directory() . '/case-study' );
} );

---

七、极简记忆口诀（方便快速使用）

• 区块名 = 文件夹名称
• --namespace = 唯一前缀（防重名）
• --category = 编辑器显示分类
• --textdomain = 翻译用文本域
• --no-plugin = 主题开发专用（不生成插件）
• npm start = 开发编译
• npm run build = 生产打包

---

八、常见错误避坑（你原文可优化点）

1. 目录多层嵌套 → 解决：在主题根目录执行命令
2. 自定义分类不显示 → 解决：必须用代码注册分类
3. 区块不加载 → 解决：必须执行 npm run build 并注册区块
4. 重名冲突 → 解决：必须设置独立 namespace
   设置进右侧 InspectorControls，中间画布主要是预览，不把主配置堆在画布上

---