Gutenberg 代码贡献环境搭建指南：从 Fork 到本地 WordPress 开发环境

Gutenberg 代码贡献环境搭建指南：从 Fork 到本地 WordPress 开发环境

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg

本篇指南面向想要向 Gutenberg（WordPress 块编辑器）项目提交代码贡献的开发者，完整讲解如何在本地搭建与项目官方一致（或高度兼容）的开发环境：包括 Fork 与克隆仓库、构建 Gutenberg 为可用的 WordPress 插件、使用wp-env与 Docker 启动本地 WordPress 实例、配置 Storybook 组件开发环境，以及将 VS Code 等编辑器接入仓库统一的 ESLint / Prettier / PHP_CodeSniffer / Stylelint 工具链。读完本文，你将掌握一套从源码到可运行插件、再到可调试可测试的完整本地开发链路。

本文内容以仓库文档 docs/contributors/code/getting-started-with-code-contribution.md 为主体骨架，并结合仓库内 package.json、.wp-env.json、packages/env/README.md、.editorconfig、eslint.config.mjs、prettier.config.mjs 等真实配置文件进行源码级佐证与扩展。

概览：贡献环境与扩展开发环境的高度重叠

为 Gutenberg 贡献代码所需的环境，与"使用 Gutenberg 扩展 WordPress 块编辑器"所需的环境存在大量重叠：两者都需要 Node.js 工具链来编译 JavaScript 源码、都需要一个可运行的 WordPress 实例来观察效果。区别只在于：贡献者面向的是仓库本体（monorepo 根目录），而扩展开发者通常面向packages目录中发布的独立 npm 包。若需要更多环境搭建的背景知识，可参考仓库中的 开发环境教程（该教程面向块开发，其中 Node.js 安装细节见 nodejs-development-environment.md）。

前置条件

Node.js

Gutenberg 本质是一个大型 JavaScript 项目，所有构建、测试、代码质量工具都运行在 Node.js 之上。当前仓库对 Node.js 版本有明确要求：根目录 package.json 的engines字段声明node >=24.18.0、npm >=11.16.0，即当前基于 Node.js v24 与 npm v11 构建。项目会尽量跟随 Node.js 的 Active LTS 版本，但并不保证永远如此，因此：

• 强烈建议使用 Node 版本管理器（nvm）来安装和管理 Node，这是 macOS、Linux 以及 Windows 10 + WSL2 环境下最简单的方案；
• 安装与切换细节可参考 开发环境教程 或 Node.js 官方站点；
• 若本机已存在其他版本 Node，请在进入仓库前切换到符合engines声明的版本，否则npm install可能因版本不符而失败。

Git 与 GitHub 账号

Gutenberg 使用 Git 进行源码管理。请确保本机安装了较新版本的 Git，并拥有一个 GitHub 账号（用于 Fork 仓库与提交 Pull Request）。关于 Gutenberg 如何使用 Git/GitHub 的完整流程（Fork、分支命名、rebase、保持 fork 同步等），请阅读仓库内 Git Workflow 文档。

Docker Desktop 与 wp-env（推荐）

推荐使用wp-env（即@wordpress/envnpm 包）在本地搭建 WordPress 环境，它需要 Docker 支持：

• wp-env是随 Gutenberg 项目一同开发的工具，用于借助 Docker 快速创建标准的 WordPress 开发环境；
• Windows 10 家庭版安装 Docker 时，需按 Docker for Windows 的 WSL2 安装说明操作；
• 如果不使用 Docker，也可以改用 Local、WampServer 或 MAMP，甚至使用远程服务器（下文各有专节）。

GitHub CLI（可选）

GitHub CLI 虽然不是硬性要求，但在本地 checkout Pull Request 时非常有用——无论是 Gutenberg 仓库还是 Fork 仓库的 PR，都能直接拉取到本地进行代码评审和测试，能显著节省时间。

获取 Gutenberg 代码

标准的 GitHub Fork + Clone 流程：

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

三步分别完成：克隆你自己的 Fork；进入仓库目录；将 WordPress 官方仓库注册为upstream远端，以便后续git fetch upstream同步主干代码。关于如何用upstream保持 fork 与主仓库同步，可参见 Git Workflow。

构建 Gutenberg 为插件

安装依赖并进入开发模式

npm install npm run dev

• npm install会安装 monorepo 全部依赖。当前仓库采用 npm workspaces 管理（见 package.json 的workspaces字段：packages/*、routes/*、storybook、test/*、tools/*、widgets/*），并配有lerna与husky（prepare脚本执行husky install安装 Git hooks）；
• npm run dev对应@wordpress/build-scripts的dev任务，会持续监听源码变化并自动增量构建。开发模式构建会额外包含调试用的警告与错误信息，便于排错；
• 注意：安装脚本要求本机已安装 Python 并加入系统 PATH。部分操作系统默认自带，否则需要手动下载安装。

每个 Git worktree 单独安装依赖

如果你使用 Git worktree 并行开发多个分支，需要在每个全新的 worktree 中重新安装依赖，再执行构建、测试、lint 或提交：

• 不要跨 worktree 复用node_modules或生成产物，尤其当各 worktree 的package-lock.json处于不同修订版本时，复用会导致结果与当前 checkout 不匹配；
• 如果使用--ignore-scripts安装依赖，请在提交前运行npm run prepare，让 Husky 安装仓库 Git hooks；
• 若某个聚焦命令需要生成的包产物，先在当前 worktree 构建受影响的包，再解读其结果。

生产构建

开发告一段落后，可运行npm run build（对应@wordpress/build-scripts的build:all）生成优化的生产构建。构建完成后，Gutenberg 目录本身就是一个完整的 WordPress 插件——根目录的 gutenberg.php 即插件主文件，配合 lib 目录下的 PHP 实现即可被 WordPress 加载。

本地 WordPress 环境

要测试一个 WordPress 插件，必须先有 WordPress 本体。

复用已有的 WordPress 安装

如果你已经有一套本地 WordPress 环境，只需把构建好的gutenberg目录放入wp-content/plugins/目录，然后在 WordPress 后台激活插件即可。

使用 Docker 与 wp-env

wp-env随 Gutenberg 项目开发，并以@wordpress/env的 npm 包形式发布。默认情况下，在插件目录内运行wp-env即可创建并启动 WordPress 环境，自动挂载并激活该插件；它还支持配置为使用既有安装、多插件、多主题等场景，完整配置见 wp-env 包文档。

先确认 Docker 正在运行，然后在gutenberg目录内执行：

npm run wp-env start

该命令会在后台基于最新 WordPress Docker 镜像创建一个 Docker 实例，并把本地 Gutenberg 插件代码以 Docker volume 方式映射进环境。你在本地改的任何代码都会立即反映到 WordPress 实例中，无需重新构建镜像。npm run会使用 Gutenberg 项目内指定的wp-env/ WordPress 版本，确保运行的是最新版本。

停止环境：

npm run wp-env stop

彻底销毁安装：

npm run wp-env destroy

更多命令（reset、cleanup、logs、status、run等）见 packages/env/README.md。仓库根目录的 .wp-env.json 是 Gutenberg 项目自身的真实配置：

{ "$schema": "./schemas/json/wp-env.json", "testsEnvironment": false, "core": "WordPress/WordPress", "plugins": [ "." ], "themes": [ "./test/emptytheme" ], "phpmyadminPort": 9000 }

从中可以看到：core指向WordPress/WordPress（使用 WordPress 主仓库默认分支构建）、当前目录.被挂载为插件、test/emptytheme被挂载为主题、phpMyAdmin 端口固定为 9000——这正解释了下文"phpMyAdmin 默认可用在 9000 端口"的行为来源。

wp-env的.wp-env.json配置字段（摘自 packages/env/README.md）：

字段	类型	默认值	说明
core	string|null	null	使用的 WordPress 安装来源，null表示最新正式版
phpVersion	string|null	null	PHP 版本，null表示与正式版配套的默认版本
plugins	string[]	[]	要安装并激活的插件列表
themes	string[]	[]	要安装的主题列表
port	integer	8888	站点 HTTP 端口
autoPort	boolean	false	配置端口被占用时自动向上寻找可用端口
config	Object	见 README	需要写入 wp-config.php 的常量映射
mappings	Object	{}	WordPress 目录到本地目录的挂载映射
mysqlPort	integer	随机	对外暴露的 MySQL 端口
phpmyadmin	boolean	false	是否启用 phpMyAdmin
phpmyadminPort	integer	随机	phpMyAdmin 端口（仅 Docker，设置即启用）
multisite	boolean	false	是否搭建多站点安装
lifecycleScripts	Object	{}	在生命周期节点执行的命令映射

注意：端口环境变量WP_ENV_PORT优先级高于.wp-env.json中的值。若启动时端口被占用，可加--auto-port参数自动选端口；wp-env还支持实验性的--runtime=playground选项，用 WordPress Playground（WebAssembly）代替 Docker 运行（完整命令选项见 packages/env/README.md）。

验证启动结果

一切正常时，终端应看到类似输出：

WordPress development site started at http://localhost:8888/ MySQL is listening on port 51220 ✔ Done! (in 261s 898ms)

在 Mac 菜单栏或 Linux/Windows 系统托盘中右键 Docker 图标选择 Dashboard，可以看到脚本已下载若干 Docker 镜像，并运行着一个功能完整的 WordPress 容器。

访问本地 WordPress 安装

• 站点地址：http://localhost:8888
• 后台地址：http://localhost:8888/wp-admin/
• 登录凭据：用户名admin，密码password

你会看到 Gutenberg 插件已安装并激活——这就是你的本地构建产物。

访问 MySQL 数据库

Gutenberg 项目默认启用 phpMyAdmin，可直接访问http://localhost:9000/（对应 .wp-env.json 中phpmyadminPort: 9000的配置）。

若要使用其他数据库工具连接，需要先获取连接信息：

1. 在终端进入本地 Gutenberg 仓库目录；
2. 运行npm run wp-env start，终端会输出大量环境信息；
3. 在输出中查找 MySQL 端口，形如MySQL is listening on port {MYSQL_PORT_NUMBER}；
4. 记下该端口号（注意：每次wp-env重启端口都会变化）；
5. 使用以下信息连接（将{MYSQL_PORT_NUMBER}替换为实际端口）：

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

若连接不上，多半是端口已变化，重复上述步骤获取新端口即可。Sequel Ace 等 GUI 工具可简化 MySQL 访问。

常见问题排查

遇到问题时，优先查阅 wp-env 文档中的 Troubleshooting 章节，其推荐的排查顺序是：检查docker ps确认容器运行 → 检查端口是否被占用 →wp-env start --update重启并更新 → 重启 Docker →wp-env reset all重置数据库 →wp-env destroy全部销毁后重建。

使用 Local 或 MAMP

不使用 Docker 时，也可用 Local、WampServer 或 MAMP 运行本地 WordPress。做法：克隆并安装 Gutenberg 为普通插件——通过软链接或直接拷贝目录到wp-content/plugins目录。

此外还需额外配置才能运行 e2e 测试。进入插件目录，为所有 e2e 测试插件创建软链接：

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

（仓库内 e2e 测试插件源码位于 packages/e2e-tests/plugins；新增插件后需重新执行此命令。）然后运行：

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

PHP 文件缓存

要正确调试 PHP 文件，需要关闭 OPCache：

• 打开MAMP > Preferences > PHP
• 在Cache下选择off
• 点击OK确认

入站连接

MAMP 启动的 Apache 默认监听所有入站连接，而不仅是本机——同一局域网（某些情况下甚至是互联网）的其他人也能访问你的服务器。这可能是有意为之（便于在其他设备上测试），但多数时候是隐私/安全隐患，切勿在服务器上存放敏感信息。若要限制为本机，可自行修改（注意风险：会破坏 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 ci严格按 lockfile 安装，适合 CI/部署场景），完成后执行npm run build。

构建完成后，克隆的 gutenberg 目录就是完整插件，可将整个仓库上传到wp-content/plugins目录并在 WordPress 后台激活。另一种方式是运行npm run build:plugin-zip（对应 package.json 中的bash ./bin/build-plugin-zip.sh，需要bash与php）生成gutenberg.zip，通过 WordPress 后台直接安装。

Storybook 组件开发

Storybook 是用于在隔离环境中开发 UI 组件的开源工具（支持 React、React Native 等）。Gutenberg 仓库内置了 Storybook 集成，允许在与 WordPress 无关的上下文中测试和开发组件——非常适合开发可复用组件、调试不依赖后端的通用 JavaScript 模块。

本地启动：

npm run storybook:dev

该命令会同时启动dev构建并等待.dev-ready信号，然后自动在浏览器中打开 Storybook 页面（见 package.json 中storybook:dev脚本的实现）。仓库内 Storybook 配置与组件故事位于 storybook 目录。

开发者工具配置

建议配置编辑器自动检查语法与 lint 错误，自动修复格式问题可显著节省开发时间。以下以核心开发者常用的 VS Code 为例，相关工具同样适用于其他编辑器。

Visual Studio Code

推荐安装以下扩展，让编辑器复用 Gutenberg 仓库的 lint、格式化、PHP 与 TypeScript 工具链：

• EditorConfig for VS Code
• PHP Intelephense
• ESLint
• Prettier - Code formatter
• PHP_CodeSniffer
• Stylelint
• Native TypeScript Preview

以下是建议的起点工作区设置文件（这些设置是可选的，应放在本地.vscode/settings.json；不要提交个人工作区设置，必要时将.vscode/settings.json加入全局 gitignore）：

{ "search.exclude": { "**/.cache/**": true, "**/build/**": true, "**/build-module/**": true, "**/build-types/**": true, "**/build-style/**": true, "**/node_modules/**": true, "**/vendor/**": true }, "[php]": { "editor.formatOnSave": true, "editor.defaultFormatter": "obliviousharmony.vscode-php-codesniffer" }, "eslint.bulkSuppression.enable": true, "eslint.bulkSuppression.location": "tools/eslint/suppressions.json", "eslint.bulkSuppression.severity": "hint", "intelephense.environment.phpVersion": "7.4.0", "intelephense.files.exclude": [ "**/.cache/**", "**/.git/**", "**/.history/**", "**/build/**", "**/build-module/**", "**/build-types/**", "**/build-style/**", "**/node_modules/**", "**/vendor/**" ], "phpCodeSniffer.autoExecutable": true, "phpCodeSniffer.standard": "Automatic", "phpCodeSniffer.exclude": [ "**/.git/**", "**/.svn/**", "**/.hg/**", "**/.cache/**", "**/build/**", "**/node_modules/**", "**/vendor/**" ], "[javascript][javascriptreact][typescript][typescriptreact]": { "editor.formatOnSave": false, "editor.defaultFormatter": "esbenp.prettier-vscode" }, "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit", "source.fixAll.stylelint": "explicit" }, "[css][scss][sass]": { "editor.formatOnSave": false, "editor.defaultFormatter": "stylelint.vscode-stylelint" }, "stylelint.validate": [ "css", "postcss", "scss" ], "js/ts.experimental.useTsgo": true }

其中eslint.bulkSuppression.location指向仓库内的 tools/eslint/suppressions.json，用于批量豁免存量 lint 告警。

EditorConfig

EditorConfig 定义编辑器的标准配置（例如用 Tab 而非空格）。安装 EditorConfig for VS Code 扩展后，编辑器会自动匹配仓库根目录 .editorconfig 的规则。该文件的真实内容为：全部文件charset = utf-8、end_of_line = lf、insert_final_newline = true、trim_trailing_whitespace = true、indent_style = tab；仅 YAML/yml 使用空格缩进（2 空格）。

ESLint

ESLint 对代码做静态分析以发现问题。lint 规则已集成进 CI 流程，必须通过才能提交。启用编辑器集成后，ESLint 会使用仓库根目录 eslint.config.mjs（flat config 格式）在开发过程中即时高亮问题。VS Code 用户使用上文扩展与设置即可；其他编辑器参考 ESLint 官方编辑器集成文档。

Prettier

Prettier 通过既定格式规则自动修复代码格式。它与 ESLint 职责相近但侧重不同：Prettier 关注格式化与风格，ESLint 侧重发现编码错误。编辑器集成使用仓库根目录 prettier.config.mjs——该文件导入 @wordpress/prettier-config 包的基础配置，并追加了changelog.txt使用 markdown 解析器的覆盖规则。

TypeScript

TypeScript 是 JavaScript 的类型化超集。Gutenberg 项目使用 TypeScript 检测类型错误，并通过编辑器集成提升开发体验（仓库根目录的 tsconfig.json 与各包内的tsconfig.json定义了类型检查范围）。VS Code 内置 TypeScript 支持，其他编辑器可参考 TypeScript 官方编辑器支持列表自行配置。

小结

至此，一条完整的 Gutenberg 代码贡献开发链路已经打通：Fork 并克隆仓库 → 按engines要求准备 Node 环境 →npm install && npm run dev持续构建 → 用npm run wp-env start拉起本地 WordPress（http://localhost:8888，phpMyAdmin 在:9000）→ 用npm run storybook:dev做无后端组件开发 → 通过 VS Code 与仓库统一的 ESLint / Prettier / PHP_CodeSniffer / Stylelint 配置保证代码质量。后续的提交流程（分支命名、rebase、提交 PR）可继续参考 Git Workflow 与 coding-guidelines.md 等文档。

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg