254 lines
14 KiB
Markdown
254 lines
14 KiB
Markdown
# 代码贡献入门指南
|
||
|
||
以下指南将帮助您设置本地环境，以便为 Gutenberg 项目做出贡献。用于贡献代码的环境与用于扩展 WordPress 区块编辑器的环境存在显著重叠。您可以查阅[开发环境教程](/docs/getting-started/devenv/README.md)获取更多设置信息。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js
|
||
Gutenberg 是一个 JavaScript 项目，需要安装 [Node.js](https://nodejs.org/)。项目目前基于 Node.js v20 和 npm v10 构建。虽然我们尽力使用 Node.js 的 Active LTS 版本，但并非总能实现。更多详细信息请参考 [Node.js 发布计划](https://github.com/nodejs/Release#release-schedule)。
|
||
|
||
我们推荐使用 [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm)，这是在 macOS、Linux 和 Windows 10（使用 WSL2）上安装和管理 Node.js 的最简单方式。如需更多安装说明，请参阅[我们的开发工具指南](/docs/getting-started/devenv/README.md#development-tools)或 Node.js 官网。
|
||
|
||
- Git
|
||
Gutenberg 使用 git 进行版本控制。请确保您的计算机上安装了最新版本的 git，并拥有 GitHub 账户。您可以阅读 [Git 工作流程](/docs/contributors/code/git-workflow.md)了解如何在 Gutenberg 中使用 git 和 GitHub。
|
||
|
||
- [推荐] Docker Desktop
|
||
我们推荐使用 [wp-env 包](/packages/env/README.md)在本地设置 WordPress 环境。使用 `wp-env` 需要安装 Docker。更多详细信息请参阅[开发环境教程](/docs/getting-started/devenv/README.md)。
|
||
> 注意：若要在 Windows 10 家庭版上安装 Docker，请按照 [Docker for Windows with WSL2 的安装说明](https://docs.docker.com/docker-for-windows/wsl/)操作。
|
||
|
||
作为 Docker 设置的替代方案，您可以使用 [Local](https://localwp.com/)、[WampServer](https://wampserver.aviatechno.net/) 或 [MAMP](https://www.mamp.info/)，甚至可以使用远程服务器。
|
||
|
||
- GitHub CLI
|
||
虽然不是必需，但 [GitHub CLI](https://cli.github.com/) 能极大帮助您在本地检出拉取请求，包括来自 Gutenberg 主仓库和分叉仓库的请求。这在代码审查和测试拉取请求时能显著节省时间。
|
||
|
||
## 获取 Gutenberg 代码
|
||
|
||
请先 Fork Gutenberg 仓库，然后克隆到您的计算机，并将 WordPress 仓库添加为上游源。
|
||
|
||
```bash
|
||
$ git clone https://github.com/您的GitHub用户名/gutenberg.git
|
||
$ cd gutenberg
|
||
$ git remote add upstream https://github.com/WordPress/gutenberg.git
|
||
```
|
||
|
||
## 将 Gutenberg 构建为插件
|
||
|
||
安装 Gutenberg 依赖项并以开发模式构建代码：
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
> 注意：安装脚本要求系统已安装 [Python](https://www.python.org/) 并配置在环境变量中。根据操作系统的不同，Python 可能已默认安装或需要手动下载安装。
|
||
|
||
有两种构建代码的方式。在开发过程中，您可能希望使用 `npm run dev` 在源文件更改时自动持续构建。开发构建还包含额外的警告和错误信息，便于开发过程中进行故障排除。完成更改后，可以运行 `npm run build` 创建优化的生产构建。
|
||
|
||
构建完成后，Gutenberg 即可作为 WordPress 插件使用！
|
||
|
||
## 本地 WordPress 环境
|
||
|
||
要测试 WordPress 插件，您需要先安装 WordPress 本体。如果您已设置好 WordPress 本地环境，只需将 gutenberg 目录放入 wp-content/plugins/ 目录即可将构建好的 Gutenberg 作为标准 WordPress 插件使用。
|
||
|
||
如果尚未设置本地 WordPress 环境，请按照本节剩余步骤创建环境。
|
||
|
||
## 开发者工具
|
||
|
||
我们建议将编辑器配置为自动检查语法和代码规范错误。这能帮助您在开发过程中自动修复细微的格式问题，从而节省时间。以下是为 Visual Studio Code（许多核心开发者常用的编辑器）的设置指南，这些工具也适用于其他编辑器。
|
||
|
||
### EditorConfig
|
||
|
||
[EditorConfig](https://editorconfig.org/) 定义了编辑器的标准配置，例如使用制表符代替空格。您应安装 [VS Code 的 EditorConfig 扩展](https://marketplace.visualstudio.com/items?itemName=editorconfig.editorconfig)，它将自动配置您的编辑器以符合 [.editorconfig](https://github.com/WordPress/gutenberg/blob/HEAD/.editorconfig) 中定义的规则。
|
||
|
||
### ESLint
|
||
|
||
[ESLint](https://eslint.org/) 通过静态分析代码来发现问题。代码规范检查规则已集成到持续集成流程中，必须通过检查才能提交代码。您应为 Visual Studio Code 安装 [ESLint 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)，其他编辑器的集成方案请参阅 [eslint 文档](https://eslint.org/docs/user-guide/integrations)。
|
||
|
||
安装扩展后，ESLint 将使用 Gutenberg 代码库根目录中的 [.eslintrc.js](https://github.com/WordPress/gutenberg/blob/HEAD/.eslintrc.js) 文件作为格式规则。它会在开发时高亮显示问题，您还可以通过以下设置实现在保存时自动修复规范问题：
|
||
|
||
```json
|
||
"editor.codeActionsOnSave": {
|
||
"source.fixAll.eslint": "explicit"
|
||
},
|
||
```
|
||
|
||
### Prettier
|
||
|
||
[Prettier](https://prettier.io/) 是一款能够定义规范化格式并自动修复代码以匹配该格式的工具。Prettier 与 ESLint 功能相似，但 Prettier 更侧重于格式和样式，而 ESLint 主要用于检测编码错误。
|
||
|
||
若要在 Visual Studio Code 中使用 Prettier，请安装 [Prettier 代码格式化扩展](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)。随后可通过在设置中添加以下配置，将其设为默认格式化工具并实现保存时自动修复问题：
|
||
**_注意_：根据文档查看环境的不同，方括号可能显示为双括号，实际正确格式应为单层方括号。**
|
||
|
||
```json
|
||
"[javascript]": {
|
||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||
"editor.formatOnSave": true
|
||
},
|
||
"[markdown]": {
|
||
"editor.defaultFormatter": "esbenp.prettier-vscode",
|
||
"editor.formatOnSave": true
|
||
},
|
||
```
|
||
|
||
此配置将使用 Gutenberg 代码库根目录中的 `.prettierrc.js` 文件，该配置继承自 [@wordpress/prettier-config](/packages/prettier-config/README.md) 包。
|
||
|
||
如果仅希望在 Gutenberg 项目中使用此配置，请在项目根目录创建 `.vscode` 文件夹，并将设置存入其中的 `settings.json` 文件。Visual Studio Code 将其称为工作区设置，且仅适用于当前项目。
|
||
|
||
其他编辑器的配置请参阅 [Prettier 编辑器集成文档](https://prettier.io/docs/en/editors.html)。
|
||
|
||
### TypeScript
|
||
|
||
**TypeScript** 是 JavaScript 语言的类型化超集。Gutenberg 项目通过 JSDoc 使用 TypeScript 来实现 [JavaScript 文件的类型检查](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html)。如果您使用 Visual Studio Code，其已内置 TypeScript 支持，其他编辑器的集成方案请参阅 [TypeScript 编辑器支持](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support)。
|
||
|
||
### 使用 Docker 与 wp-env
|
||
|
||
[wp-env 工具包](/packages/env/README.md)最初为古腾堡项目开发，旨在通过 Docker 快速创建标准 WordPress 环境。该工具已作为 `@wordpress/env` npm 包发布。
|
||
|
||
默认情况下，在插件目录中运行 `wp-env` 即可创建并启动 WordPress 环境，同时自动挂载并激活对应插件。您还可以配置 `wp-env` 以使用现有安装、多插件或主题。完整文档请参阅 [wp-env 工具包](/packages/env/README.md#wp-envjson)。
|
||
|
||
确保 Docker 处于运行状态，在古腾堡目录中执行以下命令启动 `wp-env`：
|
||
|
||
```bash
|
||
npm run wp-env start
|
||
```
|
||
|
||
该脚本将在后台创建基于最新 WordPress Docker 镜像的实例，并将本地古腾堡插件代码通过 Docker 卷映射到环境中。这样您在本地对代码的任何修改都会即时同步到 WordPress 实例中。
|
||
|
||
> 注意：`npm run` 将使用古腾堡项目内指定的 `wp-env` / `WordPress`?? 版本，确保您运行的是最新的 wp-env 版本。
|
||
|
||
停止运行环境：
|
||
|
||
```bash
|
||
npm run wp-env stop
|
||
```
|
||
|
||
若一切正常，终端将显示如下信息：
|
||
|
||
```bash
|
||
WordPress 开发站点已启动：http://localhost:8888/
|
||
WordPress 测试站点已启动：http://localhost:8889/
|
||
MySQL 正在监听端口 51220
|
||
|
||
✔ 完成！（耗时 261 秒 898 毫秒）
|
||
```
|
||
|
||
通过右键点击菜单栏（Mac）或系统托盘（Linux/Windows）中的 Docker 图标并选择「控制台」，您将看到脚本已下载若干 Docker 镜像，并正在运行包含完整 WordPress 环境的容器：
|
||
|
||
|
||
|
||
彻底删除安装环境：
|
||
|
||
```bash
|
||
npm run wp-env destroy
|
||
```
|
||
|
||
更多命令请查阅[工具包文档](/packages/env/README.md)。
|
||
|
||
#### 访问本地 WordPress 安装
|
||
|
||
WordPress 安装现已可通过 `http://localhost:8888` 访问
|
||
|
||
管理后台地址：`http://localhost:8888/wp-admin/`，登录凭据为：**用户名**：`admin`，**密码**：`password`。您会注意到古腾堡插件已安装并激活，这正是您的本地构建版本。
|
||
|
||
#### 访问 MySQL 数据库
|
||
|
||
古腾堡项目默认集成 phpMyAdmin。您可通过以下地址访问 MySQL 数据库：`http://localhost:9000/`。
|
||
|
||
若需通过其他工具访问数据库，请先获取连接信息：
|
||
|
||
1. 在终端中进入本地古腾堡代码库目录
|
||
2. 运行 `npm run wp-env start` - 终端将输出 `wp-env` 环境的相关信息
|
||
3. 在输出信息中查找 _MySQL_ 端口号：
|
||
例如：
|
||
|
||
> MySQL 正在监听端口 {MYSQL端口号}
|
||
|
||
4. 复制/记录该端口号（注意此端口号会在每次 `wp-env` 重启时变更）
|
||
5. 使用以下信息连接 MySQL 实例（请将 `{MYSQL端口号}` 替换为第三步获取的端口号）：
|
||
|
||
```
|
||
主机：127.0.0.1
|
||
用户名：root
|
||
密码：password
|
||
数据库：wordpress
|
||
端口：{MYSQL端口号}
|
||
```
|
||
|
||
**请注意**：MySQL 端口号会在每次 `wp-env` 重启时变更。若发现无法访问数据库，请重复上述步骤获取新端口号以恢复连接。
|
||
|
||
**技巧**：[Sequel Ace](https://sequel-ace.com/) 是访问 MySQL 数据库的实用图形化工具。其他工具及其使用方式可参阅 [WordPress 数据库访问指南](https://developer.wordpress.org/advanced-administration/before-install/creating-database/)。
|
||
|
||
#### 故障排除
|
||
|
||
若遇到问题，请查阅 [`wp-env` 文档中的故障排除章节](/packages/env/README.md#troubleshooting-common-problems)。
|
||
|
||
### 使用 Local 或 MAMP
|
||
|
||
作为 Docker 和 `wp-env` 的替代方案，您也可以使用 [Local](https://localwp.com/)、[WampServer](https://wampserver.aviatechno.net/) 或 [MAMP](https://www.mamp.info/) 来运行本地 WordPress 环境。为此，请通过创建符号链接或将目录复制到相应的 `wp-content/plugins` 目录中，将 Gutenberg 作为常规插件克隆并安装到您的环境中。
|
||
|
||
您还需要进行一些额外配置才能运行端到端测试。
|
||
|
||
将当前目录切换到插件文件夹，并为所有端到端测试插件创建符号链接：
|
||
|
||
```bash
|
||
ln -s gutenberg/packages/e2e-tests/plugins/* .
|
||
```
|
||
|
||
如果添加了新插件，您需要再次运行此命令。运行端到端测试的命令如下：
|
||
|
||
```bash
|
||
WP_BASE_URL=http://localhost:8888/gutenberg/ npm run test:e2e
|
||
```
|
||
|
||
#### PHP 文件缓存
|
||
|
||
您需要禁用 OPCache 才能正确编辑 PHP 文件。修复方法如下：
|
||
|
||
- 转到 **MAMP > 首选项 > PHP**
|
||
- 在 **缓存** 下选择 **关闭**
|
||
- 点击 **确定** 确认
|
||
|
||
#### 传入连接
|
||
|
||
默认情况下，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` 来创建插件压缩文件——这需要 `bash` 和 `php` 环境。该脚本会创建 `gutenberg.zip`，您可以通过 WordPress 管理后台安装 Gutenberg。
|
||
|
||
## Storybook
|
||
|
||
> Storybook 是一个开源工具，用于独立开发 React、React Native 等的 UI 组件。它使构建出色的 UI 变得有条理且高效。
|
||
|
||
Gutenberg 代码库还集成了 [Storybook](https://storybook.js.org/)，允许在与 WordPress 无关的环境中进行测试和开发。这对于开发可复用组件和尝试通用 JavaScript 模块非常有帮助，无需任何后端依赖。
|
||
|
||
您可以通过本地运行 `npm run storybook:dev` 启动 Storybook。它会自动在浏览器中打开。
|
||
|
||
您还可以在 GitHub Pages 上测试当前 `trunk` 分支的 Storybook：[https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/) |