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本篇指南面向想要向 GutenbergWordPress 块编辑器项目提交代码贡献的开发者完整讲解如何在本地搭建与项目官方一致或高度兼容的开发环境包括 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.jsGutenberg 本质是一个大型 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 devnpm install会安装 monorepo 全部依赖。当前仓库采用 npm workspaces 管理见 package.json 的workspaces字段packages/*、routes/*、storybook、test/*、tools/*、widgets/*并配有lerna与huskyprepare脚本执行husky install安装 Git hooksnpm 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-envwp-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字段类型默认值说明corestring|nullnull使用的 WordPress 安装来源null表示最新正式版phpVersionstring|nullnullPHP 版本null表示与正式版配套的默认版本pluginsstring[][]要安装并激活的插件列表themesstring[][]要安装的主题列表portinteger8888站点 HTTP 端口autoPortbooleanfalse配置端口被占用时自动向上寻找可用端口configObject见 README需要写入 wp-config.php 的常量映射mappingsObject{}WordPress 目录到本地目录的挂载映射mysqlPortinteger随机对外暴露的 MySQL 端口phpmyadminbooleanfalse是否启用 phpMyAdminphpmyadminPortinteger随机phpMyAdmin 端口仅 Docker设置即启用multisitebooleanfalse是否搭建多站点安装lifecycleScriptsObject{}在生命周期节点执行的命令映射注意端口环境变量WP_ENV_PORT优先级高于.wp-env.json中的值。若启动时端口被占用可加--auto-port参数自动选端口wp-env还支持实验性的--runtimeplayground选项用 WordPress PlaygroundWebAssembly代替 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的配置。若要使用其他数据库工具连接需要先获取连接信息在终端进入本地 Gutenberg 仓库目录运行npm run wp-env start终端会输出大量环境信息在输出中查找 MySQL 端口形如MySQL is listening on port {MYSQL_PORT_NUMBER}记下该端口号注意每次wp-env重启端口都会变化使用以下信息连接将{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_URLhttp://localhost:8888/gutenberg/ npm run test:e2ePHP 文件缓存要正确调试 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/gutenbergwp-content/themes/twentytwenty - ~/projects/twentytwenty此时需要让 Apache 允许跟随这类链接打开或新建/Applications/MAMP/htdocs/.htaccess添加一行Options SymLinksIfOwnerMatch使用 WP-CLIMAMP 这类工具常把 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 CodePHP IntelephenseESLintPrettier - Code formatterPHP_CodeSnifferStylelintNative 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 告警。EditorConfigEditorConfig 定义编辑器的标准配置例如用 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 空格。ESLintESLint 对代码做静态分析以发现问题。lint 规则已集成进 CI 流程必须通过才能提交。启用编辑器集成后ESLint 会使用仓库根目录 eslint.config.mjsflat config 格式在开发过程中即时高亮问题。VS Code 用户使用上文扩展与设置即可其他编辑器参考 ESLint 官方编辑器集成文档。PrettierPrettier 通过既定格式规则自动修复代码格式。它与 ESLint 职责相近但侧重不同Prettier 关注格式化与风格ESLint 侧重发现编码错误。编辑器集成使用仓库根目录 prettier.config.mjs——该文件导入 wordpress/prettier-config 包的基础配置并追加了changelog.txt使用 markdown 解析器的覆盖规则。TypeScriptTypeScript 是 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拉起本地 WordPresshttp://localhost:8888phpMyAdmin 在: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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考