@wordpress/create-block

最后更新：2026-10-17 10:55:29

Create Block 是一个官方支持的用于生成注册区块的 WordPress 插件的工具。它会生成 PHP、JS、CSS 代码以及项目启动所需的一切。它还集成了无需配置的现代构建环境。

它很大程度上受到 create-react-app 的启发。特别感谢 @gaearon、整个 Facebook 团队以及 React 社区。

区块是现代 WordPress 站点的基本元素。自 WordPress 5.0 引入以来，它们为每个最新的 WordPress 网站提供了类似页面和文章构建器的功能。
在 Gutenberg 手册中了解更多关于 Block API 的信息。

快速开始

$ npx @wordpress/create-block@latest todo-list
$ cd todo-list
$ npm start

提供的 slug（示例中的 todo-list）定义了生成插件的文件夹名称和内部区块名称。生成的 WordPress 插件必须手动安装。

（需要 node 版本 20.10.0 或更高）

观看 Learn.wordpress.org 上关于 create-block 的视频介绍

用法

create-block 命令会生成一个包含 PHP、JS 和 CSS 代码的项目，用于通过 WordPress 插件注册区块。

$ npx @wordpress/create-block@latest [options] [slug]

区块名称是标识区块的唯一字符串。区块名称的结构为 namespace/slug，其中 namespace 是你的插件或主题的名称。
在大多数情况下，我们建议将区块与 WordPress 插件配对而不是主题，因为仅使用插件可确保在更改主题时所有区块仍然有效。

交互模式

当未提供 slug 时，脚本将以交互模式运行，并开始提示输入所需的信息（slug、标题、namespace…）以生成项目。

namespace

默认情况下，区块是使用 create-block namespace 创建的。你应该指定自己的唯一 namespace：

$ npx @wordpress/create-block@latest my-block --namespace=my-namespace

这将创建 my-namespace/my-block 而不是 create-block/my-block。

如果你已经创建了区块，请更新以下文件中的 namespace：
– block.json – name 属性

slug

使用 slug 是可选的。

当提供时，它将触发*快速模式*，此时该 slug 将被用于：

作为区块 slug（用于识别所必需的）
作为生成文件的输出位置（文件夹名称）
作为 WordPress 插件的名称。

除非使用下面列出的一些选项进行覆盖，否则其余配置均设置为所有默认值。

options

-V, --version                输出版本号
-t, --template <name>        项目模板类型名称；允许的值："standard"（默认）、"es5"、外部 npm 包的名称或本地目录的路径
--variant                    选择由模板定义的区块变体
--no-plugin                  仅生成区块文件
--target-dir <directory>     文件生成的目录，默认为 slug
--namespace <value>          区块名称的内部 namespace
--title <value>              区块和 WordPress 插件的显示标题
--short-description <value>  区块和 WordPress 插件的简短描述
--category <name>            区块的分类名称
--wp-scripts                 启用与 `@wordpress/scripts` 包的集成
--no-wp-scripts              禁用与 `@wordpress/scripts` 包的集成
--wp-env                     启用与 `@wordpress/env` 包的集成
--textdomain <value>         国际化文本域
-h, --help                   输出使用信息

–template

此参数指定一个*外部 npm 包*作为模板。

$ npx @wordpress/create-block@latest --template my-template-package

此参数还允许选择一个*本地目录*作为模板。

$ npx @wordpress/create-block@latest --template ./path/to/template-directory

–variant

使用此参数，create-block 将基于内置模板生成一个动态区块。

$ npx @wordpress/create-block@latest --variant dynamic

–no-plugin

使用此参数，create-block 包将在*无插件模式*下运行，该模式仅将区块文件生成到当前目录中。

$ npx @wordpress/create-block@latest --no-plugin

–wp-env

使用此参数，create-block 包将在生成的插件中添加配置和脚本，以便在插件内运行wp-env 包。这将使你能够轻松设置本地 WordPress 环境（通过 Docker），用于构建和测试生成的插件。

$ npx @wordpress/create-block@latest --wp-env

–textdomain

使用此参数，create-block 包将生成一个带有提供文本域的区块。如果未指定，则使用区块的 slug 作为默认文本域。

$ npx @wordpress/create-block@latest --textdomain my-custom-domain

–help

使用此参数，create-block 包将输出使用信息。

$ npx @wordpress/create-block@latest --help

生成项目中的可用命令

执行此命令时创建的插件文件夹是一个 Node 包，具有现代构建环境，无需配置。

可以从该文件夹内部使用一组脚本（由 scripts 包提供）来简化你的工作。点击此处查看这些命令的完整描述。

注意：你不需要自己安装或配置 webpack、Babel 或 ESLint 等工具。它们已预配置并隐藏，以便你可以专注于编码。

例如，在生成的文件夹内运行 start 脚本（npm start）将自动启动开发环境的构建。

外部项目模板

点击此处获取有关外部项目模板的信息

为此包做出贡献

这是 Gutenberg 项目的一部分独立包。该项目组织为一个 monorepo。它由多个自包含的软件包组成，每个包都有特定的用途。此 monorepo 中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主体贡献者指南。