代码贡献入门

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

以下指南用于设置本地环境，以便为 Gutenberg 项目做贡献。用于贡献的环境与用于扩展 WordPress 块编辑器的环境之间存在大量重叠。您可以查阅开发环境教程以了解更多设置信息。

先决条件

Node.js
Gutenberg 是一个 JavaScript 项目，需要 Node.js。该项目目前使用 Node.js v24 和 npm v11 构建。尽管我们会尽最大努力始终使用 Node.js 的 Active LTS 版本，但并非总能如此。更多详细信息，请参阅 Node.js 发布计划。

我们推荐使用 Node Version Manager（nvm），因为对于 macOS、Linux 以及使用 WSL2 的 Windows 10 而言，它是安装和管理 Node 最简单的方式。更多安装说明请参阅我们的开发工具指南或 Nodejs 网站。

Git
Gutenberg 使用 git 进行源代码管理。请确保您的计算机上安装了最新版本的 git，并且拥有一个 GitHub 帐户。您可以阅读 Git Workflow，以了解有关在 Gutenberg 中使用 git 和 GitHub 的更多信息
[推荐] Docker Desktop
我们建议使用 wp-env 包在本地搭建 WordPress 环境。您需要安装 Docker 才能使用 wp-env。请参阅开发环境教程以了解更多详细信息。
注意：要在 Windows 10 家庭版上安装 Docker，请遵循Docker for Windows 使用 WSL2 的安装说明。

作为 Docker 设置的替代方案，您可以使用 Local、WampServer 或 MAMP，甚至可以使用远程服务器。

GitHub CLI
虽然并非必需，但 GitHub CLI 在帮助您于本地检出拉取请求（无论来自 Gutenberg 仓库还是派生仓库）方面非常有用。这在代码审查和测试拉取请求时可以节省大量时间。

获取 Gutenberg 代码

复刻 Gutenberg 仓库，将其克隆到您的计算机上，并将 WordPress 仓库添加为上游。

$ git clone https://github.com/YOUR_GITHUB_USERNAME/gutenberg.git
$ cd gutenberg
$ git remote add upstream https://github.com/WordPress/gutenberg.git

将 Gutenberg 构建为插件

安装 Gutenberg 的依赖项并以开发模式构建您的代码：

npm install
npm run dev

设置每个工作树

在每个全新的 Git 工作树中进行构建、测试、lint 或提交之前，请先在其中安装依赖项。不要复用来自 package-lock.json 处于不同修订版本的工作树的 node_modules 或生成的包文件。这种设置产生的结果可能与当前检出的内容不匹配。

如果您使用 --ignore-scripts 安装依赖项，请在提交之前运行 npm run prepare，以便 Husky 安装仓库的 Git 钩子。如果某个聚焦命令需要生成的包文件，请先在当前工作树中构建受影响的包，然后再解读其结果。

有两种构建代码的方式。在开发过程中，您可能希望使用 npm run dev，以便在源文件发生变化时自动运行持续构建。开发构建还包含额外的警告和错误，以帮助您在开发过程中排查问题。当您对所做的更改感到满意后，即可运行 npm run build 来创建经过优化的生产构建。

构建完成后，Gutenberg 就可以作为一个 WordPress 插件使用了！

本地 WordPress 环境

要测试 WordPress 插件，您需要先安装好 WordPress 本身。如果您已经搭建了 WordPress 环境，请将 gutenberg 目录放入 wp-content/plugins/ 目录中，将上述 Gutenberg 构建作为标准的 WordPress 插件使用。

如果您尚未搭建本地 WordPress 环境，请按照本节其余部分的步骤创建一个。

使用 Docker 和 wp-env

wp-env 包是随 Gutenberg 项目一起开发的，是使用 Docker 快速创建标准 WordPress 环境的方式。它也以 @wordpress/env npm 包的形式发布。

默认情况下，wp-env 可以在插件目录中运行来创建并运行一个 WordPress 环境，并自动挂载和激活插件。您还可以将 wp-env 配置为使用现有的安装、多个插件或主题。完整文档请参阅 wp-env 包。

请确保 Docker 正在运行，然后在 gutenberg 目录内启动 wp-env：

npm run wp-env start

该脚本会在幕后使用最新的 WordPress Docker 镜像创建一个 Docker 实例，然后将本地副本中的 Gutenberg 插件代码作为 Docker 卷映射到该环境中。这样，您在本地对代码所做的任何更改都会立即反映在 WordPress 实例中。

注意：npm run 将使用 Gutenberg 项目中指定的 wp-env / WordPress 版本，从而确保您运行的是最新的 wp-env 版本。

要停止正在运行的环境：

npm run wp-env stop

如果一切顺利，您应该会在终端中看到以下消息：

WordPress development site started at http://localhost:8888/
MySQL is listening on port 51220

 ✔ Done! (in 261s 898ms)

如果您通过右键单击菜单栏（Mac 上）或系统托盘（Linux 和 Windows 上）中的图标并选择“Dashboard”来打开 Docker 仪表板，您将看到该脚本已下载了一些 Docker 镜像，并且正在运行一个包含功能完整的 WordPress 安装的 Docker 容器：
正在运行的 WordPress Docker 容器截图
WordPress 开发环境已下载的 Docker 镜像截图

要彻底销毁该安装：

npm run wp-env destroy

浏览包文档以了解其他命令。

访问本地 WordPress 安装

WordPress 安装现在应该可以通过 `http://localhost:8888` 访问

您可以通过以下地址访问仪表盘：http://localhost:8888/wp-admin/` 使用**用户名**：admin，**密码**：password`。您会注意到 Gutenberg 插件已安装并激活，这就是您的本地构建。

访问 MySQL 数据库

对于 Gutenberg 项目，phpMyAdmin 默认可用。您可以通过 `http://localhost:9000/` 访问 MySQL 数据库。

如果您想通过其他工具访问数据库，首先需要获取连接详细信息。为此，请执行以下操作：

在终端中，导航到您本地的 Gutenberg 仓库。
运行 npm run wp-env start——有关 wp-env 环境的各种信息应会输出到终端中。
在第 2 步的输出中，查找有关 MySQL 端口的信息：
例如：

MySQL 正在监听端口 {MYSQL_PORT_NUMBER}

复制/记下此端口号（请注意，每次 wp-env 重新启动时，该端口号都会更改）。
现在，您可以使用以下详细信息连接到 MySQL 实例（请务必将 {MYSQL_PORT_NUMBER} 替换为第 3 步中获得的端口号）：

Host: 127.0.0.1
Username: root
Password: password
Database: wordpress
Port: {MYSQL_PORT_NUMBER}

请注意：每次 wp-env 重新启动时，MySQL 端口号都会更改。如果您发现无法再访问数据库，只需重复上述步骤找到新的端口号并恢复连接即可。

提示：Sequel Ace 是一款用于访问 MySQL 数据库的实用 GUI 工具。其他可用工具已在这篇关于访问 WordPress 数据库的文章中有所介绍。

故障排除

如果您遇到问题，请查阅wp-env 文档中的故障排除部分。

使用 Local 或 MAMP

作为 Docker 和 wp-env 的替代方案，你还可以使用 Local、WampServer 或 MAMP 来运行本地 WordPress 环境。为此，请通过创建符号链接或将目录复制到相应的 wp-content/plugins 目录，在你的安装中以常规插件的形式克隆并安装 Gutenberg。

你还需要一些额外的配置才能运行 e2e 测试。

将当前目录切换到 plugins 文件夹，并为所有 e2e 测试插件创建符号链接：

ln -s gutenberg/packages/e2e-tests/plugins/* .

如果添加了新插件，你需要重新运行此命令。要运行 e2e 测试：

WP_BASE_URL=http://localhost:8888/gutenberg/ npm run test:e2e

PHP 文件的缓存

你需要禁用 OPCache 才能正确处理 PHP 文件。修复方法如下：

转到 MAMP > Preferences > PHP
在 Cache 项下，选择 off
点击 OK 确认

传入连接

默认情况下，MAMP 启动的 Web 服务器（Apache）会监听所有传入连接，而不仅仅是本地连接。这意味着同一局域网中的任何人（在某些情况下，甚至是互联网上的任何人）都可以访问你的 Web 服务器。这可能是有意为之，并且对于在其他设备上测试站点很有用，但在大多数情况下，这可能带来隐私或安全问题。请牢记这一点，不要在此服务器中存储敏感信息。

虽然可以修复此问题，但请自担风险，因为这会破坏 MAMP 解析 Web 服务器配置的能力，进而使 MAMP 认为 Apache 监听的是错误的端口。请考虑弃用 MAMP 改用其他方案。否则，你可以采用以下方法：

编辑 /Applications/MAMP/conf/apache/httpd.conf
将 Listen 8888 改为 Listen 127.0.0.1:8888

链接到其他目录

你可能希望在 plugins 和 themes 目录中创建指向其他文件夹的链接，例如：

wp-content/plugins/gutenberg -> ~/projects/gutenberg
wp-content/themes/twentytwenty -> ~/projects/twentytwenty

如果是这样，你需要指示 Apache 允许跟随此类链接：

打开或新建 /Applications/MAMP/htdocs/.htaccess 文件
添加以下一行：Options +SymLinksIfOwnerMatch

使用 WP-CLI

MAMP 之类的工具往往将 MySQL 配置为使用默认端口 3306 以外的端口，通常偏好使用 8889。这可能会干扰 WP-CLI，使其在尝试连接数据库时失败。要解决此问题，请编辑 wp-config.php，将 DB_HOST 常量从 define( 'DB_HOST', 'localhost' ) 改为 define( 'DB_HOST', '127.0.0.1:8889' )。

在远程服务器上

你可以在开发中使用远程服务器：先在本地构建，然后将构建好的文件作为插件上传到远程服务器。

构建方法：打开终端（如果使用 Windows，则打开命令提示符），并导航到你克隆的仓库。然后输入 npm ci 来完成所有依赖项的配置。完成后，你可以输入 npm run build。

构建完成后，克隆的 gutenberg 目录中就包含了完整的插件，你可以将整个仓库上传到你的 wp-content/plugins 目录，然后在 WordPress 管理后台中激活该插件。

构建后上传的另一种方法是运行 npm run build:plugin-zip，它会创建一个 gutenberg.zip，你可以通过 WordPress 管理后台使用它来安装 Gutenberg。

Storybook

Storybook 是一款开源工具，用于为 React、React Native 等单独开发 UI 组件。它让构建精美的 UI 变得井然有序且高效。

Gutenberg 仓库还集成了 Storybook，允许在与 WordPress 无关的环境中进行测试和开发。这对于开发可复用组件以及试用不带任何后端依赖的通用 JavaScript 模块非常有帮助。

你可以在本地运行 npm run storybook:dev 来启动 Storybook。它会自动在你的浏览器中打开。

你还可以在 GitHub Pages 上测试当前 trunk 分支的 Storybook：https://wordpress.github.io/gutenberg/

开发者工具

我们建议将你的编辑器配置为自动检查语法和 lint 错误。这可以通过自动修复一些小的格式问题，帮助你在开发过程中节省时间。以下是设置 Visual Studio Code（许多核心开发者使用的流行编辑器）的一些指导；这些工具同样适用于其他编辑器。

Visual Studio Code

如果你使用 Visual Studio Code，该仓库自带一套受管理的工作区配置，使编辑器使用与 Gutenberg 仓库相同的 lint、格式化、PHP 和 TypeScript 工具。首次打开该文件夹时，VS Code 会提示你安装推荐的扩展，并允许一个自动任务，该任务会将 .vscode/settings.dist.jsonc 复制到 .vscode/settings.json。请两者都允许。随后，当 TypeScript 7 扩展询问是否使用此工作区所配置的 TypeScript 7 tsdk 时，请选择允许；否则它将继续使用其自带的版本。

只要 settings.json 的第一行是 // This is a managed VS Code settings file.，安装程序就会替换该文件，因此你在其中所做的编辑会在下次打开文件夹或运行安装程序时丢失。要保留你自己的设置，请删除该行；此后安装程序就不会再改动该文件。你可以随时通过命令面板中的 Tasks: Run Task → Install VS Code settings 重新运行它。

这些设置将 TypeScript 扩展指向安装了 TypeScript 7 的工作区，因为 TypeScript 7 并未安装在根目录的 node_modules 中。如果你维护自己的设置，请从模板中复制 js/ts.tsdk.path 和 js/ts.experimental.useTsgo。

EditorConfig

EditorConfig 定义了一套用于配置编辑器的标准，例如使用制表符而不是空格。你应该安装 EditorConfig for VS Code 扩展，它会自动配置你的编辑器，使其符合 .editorconfig 中定义的规则。

ESLint

ESLint 会对代码进行静态分析以发现问题。lint 规则已集成到持续集成流程中，必须通过才能提交。启用编辑器集成后，ESLint 将使用 Gutenberg 仓库根目录下的 eslint.config.mjs 文件，在你开发时高亮显示问题。

如果你使用 Visual Studio Code，请使用上文 Visual Studio Code 部分列出的扩展和设置。对于其他编辑器，请参阅 ESLint 编辑器集成文档。

Prettier

Prettier 是一款允许你定义一种约定格式的工具，并可自动修复代码以匹配该格式。Prettier 和 ESLint 相似，但 Prettier 更侧重于格式和风格，而 ESLint 用于检测编码错误。

编辑器集成使用 Gutenberg 仓库根目录下的 prettier.config.mjs 文件。该配置引入自 @wordpress/prettier-config 包。如果你使用 Visual Studio Code，请使用上文 Visual Studio Code 部分列出的扩展和设置。

对于其他编辑器，请参阅 Prettier 的编辑器集成文档。

TypeScript

TypeScript 是 JavaScript 语言的类型化超集。Gutenberg 项目使用 TypeScript 来检测基于类型的错误，并通过编辑器集成提升开发者体验。如果你使用 Visual Studio Code，TypeScript 支持是内置的；否则，请参阅 TypeScript 编辑器支持以了解编辑器集成相关信息。