Gutenberg 区块编辑器文档

title: "代码贡献入门指南" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Code - Contributors - Repos

代码贡献入门指南

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

前提条件

我们推荐使用 Node Version Manager (nvm)，因为这是在 macOS、Linux 和使用 WSL2 的 Windows 10 上安装和管理 Node.js 最简单的方法。更多安装说明，请参阅 我们的开发工具指南 或 Node.js 官网。

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

获取 Gutenberg 代码

Fork 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

注意：安装脚本要求系统已安装 Python 并配置在环境变量中。某些操作系统可能默认已安装，否则需要手动下载安装。

有两种构建代码的方式。开发时，建议使用 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 开发站点已启动，地址：http://localhost:8888/
MySQL 正在监听端口 51220

 ✔ 完成！(耗时 261s 898ms)

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

要完全销毁安装：

npm run wp-env destroy

更多命令请探索 包文档。

访问本地 WordPress 安装

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

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

访问 MySQL 数据库

Gutenberg 项目默认提供 phpMyAdmin。您可以通过以下地址访问 MySQL 数据库：http://localhost:9000/。

如果您想通过其他工具访问数据库，首先需要获取连接信息。操作步骤如下：

  1. 在终端中，导航到您的本地 Gutenberg 代码仓库。
  2. 运行 npm run wp-env start - 关于 wp-env 环境的各种信息将输出到终端。
  3. 在步骤 2 的输出中，查找关于 MySQL 端口的信息： 例如：

MySQL 正在监听端口 {MYSQL_PORT_NUMBER}

  1. 复制/记下此端口号（请注意，每次 wp-env 重启时此端口号都会改变）。
  2. 现在您可以使用以下详细信息连接到 MySQL 实例（请务必将 {MYSQL_PORT_NUMBER} 替换为第三步中的端口号）：
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 作为常规插件克隆并安装到你的环境中。

你还需要进行一些额外配置才能运行端到端测试。

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

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

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

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

PHP 文件缓存

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

入站连接

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

虽然可以修复此问题，但您应自行承担风险，因为它会破坏 MAMP 解析 Web 服务器配置的能力，从而导致 MAMP 认为 Apache 正在监听错误的端口。请考虑改用其他工具。否则，您可以执行以下操作：

链接到其他目录

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

如果是这样，您需要配置 Apache 以允许跟随此类链接：

使用 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 来创建插件压缩文件——这需要 bash 和 php 环境。该脚本会生成 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/

开发者工具

我们建议配置编辑器以自动检查语法和代码规范错误。这将在开发过程中通过自动修复细微的格式问题来帮助您节省时间。以下是为 Visual Studio Code（许多核心开发者使用的流行编辑器）设置这些工具的指南，这些工具也适用于其他编辑器。

EditorConfig

EditorConfig 定义了一套标准配置来设置你的编辑器，例如使用制表符而非空格。你应该安装 EditorConfig for VS Code 扩展，它将自动配置你的编辑器以匹配 .editorconfig 中定义的规则。

ESLint

ESLint 通过静态分析代码来发现问题。代码检查规则已集成到持续集成流程中，必须通过检查才能提交代码。你应该为 Visual Studio Code 安装 ESLint 扩展，更多编辑器集成请参阅 eslint 文档的编辑器集成部分。

安装扩展后，ESLint 将使用 Gutenberg 代码库根目录下的 .eslintrc.js 文件作为格式化规则。它会在开发时高亮显示问题，你也可以设置以下首选项，以便在保存时自动修复代码检查问题。

    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": "explicit"
    },

Prettier

Prettier 是一款工具，它允许您定义一种固定的代码格式，并自动修复代码以匹配该格式。Prettier 和 ESlint 类似，但 Prettier 更侧重于格式和样式，而 ESlint 用于检测编码错误。

要在 Visual Studio Code 中使用 Prettier，您应该安装 Prettier - Code formatter 扩展。然后，您可以通过在设置中添加以下内容，将其配置为默认格式化工具，并在保存时自动修复问题。注意：根据您查看此文档的位置，括号可能显示为双括号，但正确的格式仅为单括号。

"[[javascript]]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
},
"[[markdown]]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.formatOnSave": true
},

这将使用 Gutenberg 仓库根目录中包含的 .prettierrc.js 文件。该配置来自 @wordpress/prettier-config 包。

如果您只想在 Gutenberg 项目中使用此配置，请在 Gutenberg 的顶层创建一个名为 .vscode 的目录，并将您的设置放在该目录的 settings.json 文件中。Visual Studio Code 将此称为工作区设置，仅适用于该项目。

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

TypeScript

TypeScript 是 JavaScript 语言的类型化超集。Gutenberg 项目通过 JSDoc 使用 TypeScript 来对 JavaScript 文件进行类型检查。如果你使用 Visual Studio Code，它内置了 TypeScript 支持，否则请参阅 TypeScript 编辑器支持以了解编辑器集成。