Gatsby v5.16 发布：支持 React 19 与 Node.js 24

欢迎使用 gatsby@5.16.0 版本（2026年1月）

本次发布的主要亮点：

• React 19 支持！
• Node.js 24 支持

此外，请参阅重要修复和改进。

上一个版本说明

完整变更日志

React 19

🔐 请注意，截至 2026 年 1 月 26 日，React 19 的安全漏洞均不影响 Gatsby。

🚀 React 19 已到来！

React 19 现已获得 Gatsby 及所有由 Gatsby 团队维护的 gatsby- 包的官方支持。

这不构成破坏性更新。你可以在继续使用 React 18 的同时，安全地升级到此版本。

所有包中对 react 和 react-dom 的 peer dependencies 已从 ^18.0.0 扩展至 ^18.0.0 || ^19.0.0。

所有现有的稳定Gatsby 功能现在均适配 React 19。

PR: https://github.com/gatsbyjs/gatsby/pull/39306

升级指南

⚠️ 社区插件可能尚未更新以支持 React 19，请查看其仓库以了解当前状态。由 Gatsby 团队管理的所有插件（位于 gatsbyjs/gatsby 仓库中）均已更新。

要升级到 React 19，首先将 gatsby 及所有以 gatsby- 开头的依赖项升级到最新版本。（如果需要帮助，请参阅本指南。）

💬 如果你使用 npm 7 或更高版本，需要使用 --legacy-peer-deps 选项。例如，如果你使用 gatsby 和 gatsby-plugin-postcss：

然后，按照 React 19 升级指南操作。无需其他更改。

请注意：

• 部分 新的 React 19 功能目前可能尚未通过 Gatsby 提供。
  • 尤其是新的 文档元数据提升（metadata hoisting）功能 在 Gatsby 中已被禁用，因为它与现有的 Gatsby Head API 存在冲突
• Gatsby 的 部分水合（Partial Hydration） 功能已实验性支持三年，目前已知 与 React 19 不兼容。如果你依赖此功能，请勿升级至 React 19。

新特性

Gatsby 现已支持 React 19 新增的根错误回调（root error callbacks）。

用户可从 gatsby-browser.js 中导出 onCaughtError 和 onUncaughtError，分别处理由错误边界捕获的错误和未捕获的错误：

在开发环境下，这些错误也会出现在 Gatsby 的 Fast Refresh 错误覆盖层中。这些回调仅在 React 19 中触发。

Node.js 24

Node.js 24 现已得到 Gatsby 官方支持。

相关 PR：https://github.com/gatsbyjs/gatsby/pull/39380 和 https://github.com/gatsbyjs/gatsby/pull/39398

重要修复与改进

• gatsby、gatsby-source-drupal：
  • fix(deps)：升级 body-parser 以解决 qs 的漏洞警告，由 @serhalp 提交于 https://github.com/gatsbyjs/gatsby/pull/39396
• chore：移除各类过时、无效或具有误导性的贡献者说明，由 @serhalp 提交于 https://github.com/gatsbyjs/gatsby/pull/39363