Gutenberg 与 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 各主版本内置的 Gutenberg 编辑器版本对应关系并深入讲解该映射关系在源码层面的落地方式版本常量定义、资源缓存版本、数据迁移、兼容层目录等帮助开发者、插件作者和测试人员快速判断环境版本、准确定位并上报问题。为什么需要一份版本权威映射表Gutenberg 作为 WordPress 区块编辑器的独立开发插件其版本迭代远快于 WordPress 主版本每一次 WordPress 主版本发布时都会内置当时最新的 Gutenberg 版本。由于两套版本号并存社区长期面临两类困惑调试问题时不知道该以哪个版本来描述环境上报 bug 时无法准确说明我用的编辑器到底是哪个 Gutenberg 版本。为此Gutenberg 官方维护者在文档中明确表示本文档的定位是Gutenberg 版本与 WordPress 主版本集成关系的权威对照表canonical list并欢迎任何人指出表中可能存在的错误官方在 WordPress.org Slack 的#core-editor频道讨论此类问题。WordPress 各主版本内置的 Gutenberg 版本对照表以下为官方文档提供的完整映射关系WordPress 5.0 至今。表中 WordPress 版本均以.X后缀表示该主版本下的所有小版本如 6.8.1、6.8.2、6.8.3Gutenberg 版本WordPress 版本23.67.1.X22.67.0.X21.96.9.X20.46.8.X19.36.7.X18.56.6.X17.76.5.X16.76.4.X16.16.3.X15.16.2.X14.16.1.X13.06.0.X11.95.9.X10.75.8.X9.95.7.X9.25.6.X8.55.5.X7.55.4.X6.55.3.X5.45.2.X4.85.1.X4.7.15.0.3-5.0.224.7.05.0.24.6.15.0.0-5.0.1读表要点主版本对应是基准版本表中每一行给出的是该 WordPress 主版本发布时内置的 Gutenberg 基线版本例如 WordPress 6.8 内置 Gutenberg 20.4。WordPress 5.0 阶段版本粒度较细5.0 系列早期5.0.0–5.0.1 用 Gutenberg 4.6.1、5.0.2 用 4.7.0、5.0.3 起用 4.7.1处于编辑器刚并入核心的过渡期映射表按具体小版本细分从 5.1 开始才统一为一个主版本对应一个 Gutenberg 基准版本的粒度。两个关键规则beta 期补丁与 point release 补丁官方文档特别强调了两条容易引发混淆的规则规则一WordPress beta 期间会额外并入后续 Gutenberg 修复在某个 WordPress 版本的 beta 阶段若后续更新的 Gutenberg 版本中出现了必要修复官方会将这些修复定向挑选进即将发布的 WordPress 版本中。因此你实际拿到的编辑器代码可能比映射表中标注的基准版本包含更多来自更新的 Gutenberg 版本的 bug 修复——但版本号本身不会改变。规则二point release小版本也会携带精选修复这一规则从Gutenberg 4.8 / WordPress 5.1 起正式生效WordPress 6.8 内置 Gutenberg 20.4但 6.8.1、6.8.2、6.8.3 同样包含了 Gutenberg 20.4 之后的非常具体的 bug 修复而基准版本仍然是 20.4。也就是说WordPress 的X.Y.Z小版本升级往往伴随着从更新的 Gutenberg 版本中 cherry-pick 回来的安全与稳定性修复但内置编辑器的对外版本号保持不变。这解释了为什么WordPress 版本 内置 Gutenberg 基准版本都无法精确描述你机器上编辑器的实际代码状态——只有查看具体变更记录才能确认是否包含了某个后续修复。实践含义上报 bug 时应同时提供 WordPress 版本号与若安装了插件版的Gutenberg 插件版本号并尽量说明是否使用最新小版本复现问题时若怀疑某个修复为什么在我的版本里没有应先核对 point release 是否已包含该修复而非直接断定版本映射有误想了解映射表之外的每个 Gutenberg 具体发布内容应查阅各版本的官方发布说明文档明确指向 Make Core 上以gutenberg-new标签发布的发布笔记。源码印证一Gutenberg 版本号在仓库中如何定义映射表中的Gutenberg 版本与当前仓库的开发版本是两个体系。当前仓库作为插件本体其版本号定义在插件入口文件 gutenberg.php 的插件头中/** * Plugin Name: Gutenberg * Description: Printing since 1440. This is the development plugin for the block editor, site editor, and other future WordPress core functionality. * Requires at least: 7.0 * Requires PHP: 7.4 * Version: 24.0.0-rc.1 */同时入口文件还定义了插件运行的最低 WordPress 版本常量gutenberg.php#L15defined( GUTENBERG_MINIMUM_WP_VERSION ) or define( GUTENBERG_MINIMUM_WP_VERSION, 7.0 );入口文件中的 gutenberg_pre_init() 会读取 WordPress 的$wp_version全局变量剥离-src后缀后用version_compare()与GUTENBERG_MINIMUM_WP_VERSION比较若当前 WordPress 版本低于要求则显示版本提示并自动停用插件gutenberg_wordpress_version_notice。这也是Gutenberg 需要对应版本 WordPress这一理念在插件层面的直接体现——而映射表则是WordPress 反过来内置哪个 Gutenberg的另一面。运行时版本常量build/constants.php插件真正在运行时使用的版本常量由构建产物定义。在 lib/load.php#L23-L29 中可以看到其加载逻辑// Define version constant for backwards compatibility. // The constants.php file returns an array but doesnt define constants to avoid conflicts. $constants_file plugin_dir_path( __DIR__ ) . build/constants.php; if ( file_exists( $constants_file ) ! defined( GUTENBERG_VERSION ) ) { $build_constants require $constants_file; define( GUTENBERG_VERSION, $build_constants[version] ); }从源码注释可以看出设计意图build/constants.php只返回数组、不直接定义常量以避免与 WordPress 核心或其他插件发生常量冲突然后由 Gutenberg 自行决定是否定义GUTENBERG_VERSION。源码印证二版本号在运行时的三大实际用途GUTENBERG_VERSION定义后在运行时至少有三种关键用途理解它们有助于诊断修改了代码但浏览器看不到效果一类问题。1. 前端资源缓存版本号lib/client-assets.php#L125 与 lib/blocks.php#L131 中都用同一模式为脚本/样式设置版本号$version defined( GUTENBERG_VERSION ) ! SCRIPT_DEBUG ? GUTENBERG_VERSION : time();生产环境非SCRIPT_DEBUG下资源 URL 携带?verGUTENBERG_VERSION用于浏览器缓存失效SCRIPT_DEBUG开启时直接使用time()保证开发期每次加载都是最新文件。因此如果插件版本号未更新即使代码发生了变更生产环境的浏览器也可能命中旧缓存——这是调试时判断是不是缓存问题的一个直接依据。2. 数据迁移版本门控lib/upgrade.php 使用独立的迁移常量_GUTENBERG_VERSION_MIGRATION当前值为23.9.0并通过get_option( gutenberg_version_migration )记录插件已完成的迁移版本$gutenberg_installed_version get_option( gutenberg_version_migration, 9.7.0 ); if ( _GUTENBERG_VERSION_MIGRATION ! $gutenberg_installed_version ) { // 逐步执行版本小于阈值的迁移 // version_compare( $gutenberg_installed_version, 9.8.0, ) // version_compare( $gutenberg_installed_version, 23.8.0, ) // version_compare( $gutenberg_installed_version, 23.9.0, ) update_option( gutenberg_version_migration, _GUTENBERG_VERSION_MIGRATION ); }这是版本号驱动功能演进的典型实现每次大版本升级都会检查存量安装点按版本阈值执行对应的数据升级避免一次性重放全部迁移逻辑。3. WordPress 版本驱动的兼容分支在 lib/block-template-utils.php#L21 中可以看到直接读取 WordPress 版本、生成 theme.json 版本前缀的用法$theme_json_version wp/ . substr( $wp_version, 0, 3 );即按$wp_version的主版本号如7.1、6.8动态拼出wp/7.1这类版本标识——与映射表中的主版本粒度保持一致。源码印证三映射关系如何指导发布与兼容维护发布流程中的版本对齐发布脚本 tools/release/generate-php-sync-issue.mjs#L69 在生成PHP 同步 issue时要求传入--since参数其参数说明直接引用本文档Error. The --since argument is required (e.g. YYYY-MM-DD). This should be the date of the final Gutenberg release that was included in the last stable WP Core release (seedocs/contributors/versions-in-wordpress.md)。这说明版本映射表是 WordPress 核心与 Gutenberg 同步工作的重要输入同步范围的起点正是上一次稳定 WordPress 版本所包含的最后一个 Gutenberg 发布。按 WordPress 版本组织的兼容层仓库在 lib/compat 目录下按目标 WordPress 版本维护向后兼容实现当前存在lib/compat/wordpress-7.1/包含 admin-bar、block-bindings、icons、rest-api、view-config-api 等 17 个文件的 7.1 兼容层lib/compat/wordpress-7.2/包含 templates controller、view-config 等 5 个文件的 7.2 兼容层lib/compat/plugin/仅针对插件形态的兼容代码如 edit-site 路由向后兼容、字体、connectors、样式状态别名。lib/load.php 会按当前环境依次引入这些兼容文件见 lib/load.php#L53-L110。这种目录名 WordPress 版本号的组织方式与映射表一脉相承每个 WordPress 主版本内置的编辑器功能基线不同插件必须在同一份代码里为不同基线提供差异化实现。实战如何核对你的环境并有效上报问题结合上述规则与源码推荐按以下步骤排查确认 WordPress 主版本后台仪表盘 → 更新页面或直接读取$wp_version在wp-includes/version.php。查询映射表根据主版本在本文对照表中找到内置的 Gutenberg 基准版本如 WordPress 6.8 → Gutenberg 20.4。确认是否装有 Gutenberg 插件若同时启用了插件版插件版本以 gutenberg.php 插件头中的Version字段为准当前开发仓库为24.0.0-rc.1插件还要求 WordPress ≥GUTENBERG_MINIMUM_WP_VERSION当前为 7.0不满足时会被自动停用。排除 point release 差异如果你的 WordPress 版本号带有小版本如 6.8.3其实际代码可能包含基准版本之后从更新的 Gutenberg 中挑选的修复不要仅凭基准版本断言功能缺失。上报信息至少提供 WordPress 完整版本号含小版本、Gutenberg 插件版本号如安装、复现步骤涉及缓存问题时可结合SCRIPT_DEBUG与GUTENBERG_VERSION的缓存版本机制说明现象。总结WordPress 各主版本内置的 Gutenberg 版本映射是理解编辑器版本差异的第一手权威资料。掌握三点即可避免绝大多数版本困惑主版本对应基准 Gutenberg 版本beta 期与 point release 会额外携带精选修复而版本号不变映射表同时是官方同步发布流程的起点依据。在此基础上结合仓库中的GUTENBERG_VERSION常量、lib/compat版本化兼容层与升级迁移机制即可对编辑器环境做出准确判断并高效完成 bug 定位与上报。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Gutenberg 与 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 各主版本内置的 Gutenberg 编辑器版本对应关系并深入讲解该映射关系在源码层面的落地方式版本常量定义、资源缓存版本、数据迁移、兼容层目录等帮助开发者、插件作者和测试人员快速判断环境版本、准确定位并上报问题。为什么需要一份版本权威映射表Gutenberg 作为 WordPress 区块编辑器的独立开发插件其版本迭代远快于 WordPress 主版本每一次 WordPress 主版本发布时都会内置当时最新的 Gutenberg 版本。由于两套版本号并存社区长期面临两类困惑调试问题时不知道该以哪个版本来描述环境上报 bug 时无法准确说明我用的编辑器到底是哪个 Gutenberg 版本。为此Gutenberg 官方维护者在文档中明确表示本文档的定位是Gutenberg 版本与 WordPress 主版本集成关系的权威对照表canonical list并欢迎任何人指出表中可能存在的错误官方在 WordPress.org Slack 的#core-editor频道讨论此类问题。WordPress 各主版本内置的 Gutenberg 版本对照表以下为官方文档提供的完整映射关系WordPress 5.0 至今。表中 WordPress 版本均以.X后缀表示该主版本下的所有小版本如 6.8.1、6.8.2、6.8.3Gutenberg 版本WordPress 版本23.67.1.X22.67.0.X21.96.9.X20.46.8.X19.36.7.X18.56.6.X17.76.5.X16.76.4.X16.16.3.X15.16.2.X14.16.1.X13.06.0.X11.95.9.X10.75.8.X9.95.7.X9.25.6.X8.55.5.X7.55.4.X6.55.3.X5.45.2.X4.85.1.X4.7.15.0.3-5.0.224.7.05.0.24.6.15.0.0-5.0.1读表要点主版本对应是基准版本表中每一行给出的是该 WordPress 主版本发布时内置的 Gutenberg 基线版本例如 WordPress 6.8 内置 Gutenberg 20.4。WordPress 5.0 阶段版本粒度较细5.0 系列早期5.0.0–5.0.1 用 Gutenberg 4.6.1、5.0.2 用 4.7.0、5.0.3 起用 4.7.1处于编辑器刚并入核心的过渡期映射表按具体小版本细分从 5.1 开始才统一为一个主版本对应一个 Gutenberg 基准版本的粒度。两个关键规则beta 期补丁与 point release 补丁官方文档特别强调了两条容易引发混淆的规则规则一WordPress beta 期间会额外并入后续 Gutenberg 修复在某个 WordPress 版本的 beta 阶段若后续更新的 Gutenberg 版本中出现了必要修复官方会将这些修复定向挑选进即将发布的 WordPress 版本中。因此你实际拿到的编辑器代码可能比映射表中标注的基准版本包含更多来自更新的 Gutenberg 版本的 bug 修复——但版本号本身不会改变。规则二point release小版本也会携带精选修复这一规则从Gutenberg 4.8 / WordPress 5.1 起正式生效WordPress 6.8 内置 Gutenberg 20.4但 6.8.1、6.8.2、6.8.3 同样包含了 Gutenberg 20.4 之后的非常具体的 bug 修复而基准版本仍然是 20.4。也就是说WordPress 的X.Y.Z小版本升级往往伴随着从更新的 Gutenberg 版本中 cherry-pick 回来的安全与稳定性修复但内置编辑器的对外版本号保持不变。这解释了为什么WordPress 版本 内置 Gutenberg 基准版本都无法精确描述你机器上编辑器的实际代码状态——只有查看具体变更记录才能确认是否包含了某个后续修复。实践含义上报 bug 时应同时提供 WordPress 版本号与若安装了插件版的Gutenberg 插件版本号并尽量说明是否使用最新小版本复现问题时若怀疑某个修复为什么在我的版本里没有应先核对 point release 是否已包含该修复而非直接断定版本映射有误想了解映射表之外的每个 Gutenberg 具体发布内容应查阅各版本的官方发布说明文档明确指向 Make Core 上以gutenberg-new标签发布的发布笔记。源码印证一Gutenberg 版本号在仓库中如何定义映射表中的Gutenberg 版本与当前仓库的开发版本是两个体系。当前仓库作为插件本体其版本号定义在插件入口文件 gutenberg.php 的插件头中/** * Plugin Name: Gutenberg * Description: Printing since 1440. This is the development plugin for the block editor, site editor, and other future WordPress core functionality. * Requires at least: 7.0 * Requires PHP: 7.4 * Version: 24.0.0-rc.1 */同时入口文件还定义了插件运行的最低 WordPress 版本常量gutenberg.php#L15defined( GUTENBERG_MINIMUM_WP_VERSION ) or define( GUTENBERG_MINIMUM_WP_VERSION, 7.0 );入口文件中的 gutenberg_pre_init() 会读取 WordPress 的$wp_version全局变量剥离-src后缀后用version_compare()与GUTENBERG_MINIMUM_WP_VERSION比较若当前 WordPress 版本低于要求则显示版本提示并自动停用插件gutenberg_wordpress_version_notice。这也是Gutenberg 需要对应版本 WordPress这一理念在插件层面的直接体现——而映射表则是WordPress 反过来内置哪个 Gutenberg的另一面。运行时版本常量build/constants.php插件真正在运行时使用的版本常量由构建产物定义。在 lib/load.php#L23-L29 中可以看到其加载逻辑// Define version constant for backwards compatibility. // The constants.php file returns an array but doesnt define constants to avoid conflicts. $constants_file plugin_dir_path( __DIR__ ) . build/constants.php; if ( file_exists( $constants_file ) ! defined( GUTENBERG_VERSION ) ) { $build_constants require $constants_file; define( GUTENBERG_VERSION, $build_constants[version] ); }从源码注释可以看出设计意图build/constants.php只返回数组、不直接定义常量以避免与 WordPress 核心或其他插件发生常量冲突然后由 Gutenberg 自行决定是否定义GUTENBERG_VERSION。源码印证二版本号在运行时的三大实际用途GUTENBERG_VERSION定义后在运行时至少有三种关键用途理解它们有助于诊断修改了代码但浏览器看不到效果一类问题。1. 前端资源缓存版本号lib/client-assets.php#L125 与 lib/blocks.php#L131 中都用同一模式为脚本/样式设置版本号$version defined( GUTENBERG_VERSION ) ! SCRIPT_DEBUG ? GUTENBERG_VERSION : time();生产环境非SCRIPT_DEBUG下资源 URL 携带?verGUTENBERG_VERSION用于浏览器缓存失效SCRIPT_DEBUG开启时直接使用time()保证开发期每次加载都是最新文件。因此如果插件版本号未更新即使代码发生了变更生产环境的浏览器也可能命中旧缓存——这是调试时判断是不是缓存问题的一个直接依据。2. 数据迁移版本门控lib/upgrade.php 使用独立的迁移常量_GUTENBERG_VERSION_MIGRATION当前值为23.9.0并通过get_option( gutenberg_version_migration )记录插件已完成的迁移版本$gutenberg_installed_version get_option( gutenberg_version_migration, 9.7.0 ); if ( _GUTENBERG_VERSION_MIGRATION ! $gutenberg_installed_version ) { // 逐步执行版本小于阈值的迁移 // version_compare( $gutenberg_installed_version, 9.8.0, ) // version_compare( $gutenberg_installed_version, 23.8.0, ) // version_compare( $gutenberg_installed_version, 23.9.0, ) update_option( gutenberg_version_migration, _GUTENBERG_VERSION_MIGRATION ); }这是版本号驱动功能演进的典型实现每次大版本升级都会检查存量安装点按版本阈值执行对应的数据升级避免一次性重放全部迁移逻辑。3. WordPress 版本驱动的兼容分支在 lib/block-template-utils.php#L21 中可以看到直接读取 WordPress 版本、生成 theme.json 版本前缀的用法$theme_json_version wp/ . substr( $wp_version, 0, 3 );即按$wp_version的主版本号如7.1、6.8动态拼出wp/7.1这类版本标识——与映射表中的主版本粒度保持一致。源码印证三映射关系如何指导发布与兼容维护发布流程中的版本对齐发布脚本 tools/release/generate-php-sync-issue.mjs#L69 在生成PHP 同步 issue时要求传入--since参数其参数说明直接引用本文档Error. The --since argument is required (e.g. YYYY-MM-DD). This should be the date of the final Gutenberg release that was included in the last stable WP Core release (seedocs/contributors/versions-in-wordpress.md)。这说明版本映射表是 WordPress 核心与 Gutenberg 同步工作的重要输入同步范围的起点正是上一次稳定 WordPress 版本所包含的最后一个 Gutenberg 发布。按 WordPress 版本组织的兼容层仓库在 lib/compat 目录下按目标 WordPress 版本维护向后兼容实现当前存在lib/compat/wordpress-7.1/包含 admin-bar、block-bindings、icons、rest-api、view-config-api 等 17 个文件的 7.1 兼容层lib/compat/wordpress-7.2/包含 templates controller、view-config 等 5 个文件的 7.2 兼容层lib/compat/plugin/仅针对插件形态的兼容代码如 edit-site 路由向后兼容、字体、connectors、样式状态别名。lib/load.php 会按当前环境依次引入这些兼容文件见 lib/load.php#L53-L110。这种目录名 WordPress 版本号的组织方式与映射表一脉相承每个 WordPress 主版本内置的编辑器功能基线不同插件必须在同一份代码里为不同基线提供差异化实现。实战如何核对你的环境并有效上报问题结合上述规则与源码推荐按以下步骤排查确认 WordPress 主版本后台仪表盘 → 更新页面或直接读取$wp_version在wp-includes/version.php。查询映射表根据主版本在本文对照表中找到内置的 Gutenberg 基准版本如 WordPress 6.8 → Gutenberg 20.4。确认是否装有 Gutenberg 插件若同时启用了插件版插件版本以 gutenberg.php 插件头中的Version字段为准当前开发仓库为24.0.0-rc.1插件还要求 WordPress ≥GUTENBERG_MINIMUM_WP_VERSION当前为 7.0不满足时会被自动停用。排除 point release 差异如果你的 WordPress 版本号带有小版本如 6.8.3其实际代码可能包含基准版本之后从更新的 Gutenberg 中挑选的修复不要仅凭基准版本断言功能缺失。上报信息至少提供 WordPress 完整版本号含小版本、Gutenberg 插件版本号如安装、复现步骤涉及缓存问题时可结合SCRIPT_DEBUG与GUTENBERG_VERSION的缓存版本机制说明现象。总结WordPress 各主版本内置的 Gutenberg 版本映射是理解编辑器版本差异的第一手权威资料。掌握三点即可避免绝大多数版本困惑主版本对应基准 Gutenberg 版本beta 期与 point release 会额外携带精选修复而版本号不变映射表同时是官方同步发布流程的起点依据。在此基础上结合仓库中的GUTENBERG_VERSION常量、lib/compat版本化兼容层与升级迁移机制即可对编辑器环境做出准确判断并高效完成 bug 定位与上报。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
