Back返回博客

Next.js 15.2

Next.js 15.2 包含错误调试、元数据、Turbopack 等方面的更新。

Next.js 15.2 包含以下更新内容：

立即升级，或通过以下命令开始使用：

终端
# 使用自动化升级 CLI
npx @next/codemod@canary upgrade latest
 
# ...或手动升级
npm install next@latest react@latest react-dom@latest
 
# ...或创建新项目
npx create-next-app@latest

重新设计的错误界面与改进的堆栈追踪

我们为应用构建过程中可能遇到的错误添加了视觉和质量上的改进。以下是各项改进的详细介绍：

错误覆盖层

Next.js 15.2 版本后的错误覆盖层示例

我们彻底改进了 Next.js 中错误消息的界面呈现方式，使其更易于理解。新设计突出显示错误的核心细节——包括错误信息、相关代码框架和调用堆栈——同时减少了来自库或依赖项代码的干扰。这意味着您可以快速定位问题根源并加速修复流程。

通过利用 React 新引入的 owner stacks 功能，我们现在能更精准地定位错误来源。Next.js 现在可以显示抛出错误的子组件，跳过那些与错误元素创建无关的中间组件。

我们还简化了偏好设置的自定义流程，无需额外配置即可调整指示器选项。

Next.js 开发工具偏好设置示例

我们在错误覆盖层底部新增了反馈区域，您可以对错误信息的帮助程度进行评分。您的意见将帮助我们理解常见痛点并改进错误提示，使调试过程更加顺畅。

开发指示器

开发指示器的多种状态展示，从渲染到显示附加信息。

我们将开发信息整合到一个全新的精简指示器中，可显示渲染模式、构建状态等详细信息。

在编译过程中，路由切换时会显示一个半透明动画的 Next.js 标志。当编译完成且 React 开始渲染时，标志会变亮，为您提供应用状态的视觉反馈。

现在打开开发指示器将显示：

  • 当前路由的渲染模式（静态/动态）
  • Turbopack 编译状态
  • 活动错误及快速访问错误覆盖层的入口

未来更新将扩展此菜单功能，包括：

  • PPR（部分预渲染）调试工具
  • 缓存监控功能
  • 其他开发者工具

这种统一的设计将所有关键开发信息集中在一处。我们将根据您的反馈在后续版本中持续优化此功能。

流式元数据

在 generateMetadata 中获取动态数据或执行异步操作通常是必要的。在之前的 Next.js 版本中，这些元数据必须在初始 UI 发送前完成生成，以便包含在文档 <head> 中。

这意味着对于许多已经具备快速初始 UI 的页面，首次绘制仍会被不影响视觉呈现的数据需求所延迟。我们在 15.2 版本中改进了这一点，允许在 generateMetadata 完成前就将初始 UI 发送至浏览器。

Next.js 开发工具偏好设置示例

但为了保持与需要文档 <head> 中元数据的爬虫程序的兼容性，我们仍会延迟向特定爬虫用户代理发送 HTML。如需更精细地控制哪些爬虫受此影响，您可以通过 next.config.js 中的 htmlLimitedBots 选项自定义匹配规则。

了解更多关于流式元数据的信息。

Turbopack 性能优化

Turbopack 在 Next.js 15 中已标记为稳定版本。

我们持续优化 Turbopack 的性能表现，特别是在无持久缓存场景下的表现。本次发布包含以下改进：

  • 更快的编译速度：早期使用者报告路由访问速度相比 Next.js 15.1 提升高达 57.6%
  • 更低的内存占用：在 vercel.com 应用中观察到本地开发时内存使用量减少 30%

经过这些优化，Turbopack 现在应该能在几乎所有场景下都比 Webpack 更快。如果在您的应用中遇到例外情况，请与我们联系——我们非常希望调查这些案例。

我们在持久缓存和生产构建方面也取得了进展。虽然这些功能尚未准备好进行实验性发布，但已开始在真实项目中进行测试。待功能更完善后，我们将分享更详细的性能指标。

React 视图过渡（实验性）

我们新增了功能标志来启用 React 中实验性的视图过渡 API。这个新 API 允许您在应用的不同视图和组件之间实现动画过渡。

要启用此功能，请在 next.config.js 中添加以下配置：

next.config.js
module.exports = {
  experimental: {
    viewTransition: true,
  },
};

注意：此功能处于高度实验阶段，未来版本可能会有变更。

关于如何使用此功能的更多信息，请参考 React 仓库中的原始视图过渡 PR。这项工作基于浏览器原生的视图过渡实现。

随着功能稳定性的提升，我们将发布更多文档和示例。

Node.js 中间件（实验性）

我们开发了新的实验性标志，允许在 Next.js 中间件中使用 Node.js 运行时。

要启用此功能，请在 next.config.js 中添加以下配置：

next.config.js
module.exports = {
  experimental: {
    nodeMiddleware: true,
  },
};

然后您可以在中间件的 config 导出中指定 Node.js 运行时：

middleware.js
import bcrypt from 'bcrypt';
 
const API_KEY_HASH = process.env.API_KEY_HASH; // 环境变量中预哈希处理的 API 密钥
 
export default async function middleware(req) {
  const apiKey = req.headers.get('x-api-key');
 
  if (!apiKey || !(await bcrypt.compare(apiKey, API_KEY_HASH))) {
    return new Response('禁止访问', { status: 403 });
  }
 
  console.log('API 密钥验证通过');
}
 
export const config = {
  runtime: 'nodejs',
};

注意：此功能尚不建议用于生产环境。因此除非您使用 next@canary 版本而非稳定版，否则 Next.js 会抛出错误。

我们计划借此机会改进和重塑中间件 API。如果您有任何建议或需求，请告诉我们。Node.js 中间件是社区最期待的功能之一，我们很高兴能实现这一需求。

即将推出

  • "use cache"（测试版）：我们正在稳定独立功能的 "use cache"。敬请关注后续版本中的更多细节。了解更多关于 "use cache" 的信息。
  • Turbopack 持久缓存（实验性）：我们已在 Vercel 内部使用持久缓存功能并观察到积极的性能提升。待进一步稳定后，我们将通过功能标志发布该功能以收集更多反馈和测试。

其他变更

  • [功能] 为 create-next-app 添加 --api 标志以创建无头 API 专用项目 (PR)
  • [功能] 为 next/image 添加 images.qualities 支持 (PR)
  • [弃用] 在 App Router 中提示 i18n 配置即将弃用 (PR)
  • [改进] 提升 no-html-link-for-pages 的 lint 性能 (PR)
  • [改进] 当 "use action" 指令使用不当时抛出构建错误 (PR)
  • [改进] 开发时在错误覆盖层旁显示 global-error (PR)
  • [改进] 允许禁用开发服务器的 HTTP 请求日志 (PR)
  • [改进] 添加分页 SEO 链接标签 (PR)
  • [改进] 改进 metadata 和 <Link> 组件的 JSDocs (PR)
  • [改进] 中间件应匹配 next/image 请求 (PR)
  • [改进] 在默认错误边界消息中添加主机名 (PR)
  • [改进] 通过 reportError 发送未由显式错误边界处理的错误 (PR)

贡献者

Next.js 是超过 3,000 位开发者共同协作的成果。本次发布的贡献者包括：

特别感谢 @mischnic、@Marukome0743、@JamBalaya56562、@creationix、@noreiller、@styfle、@abdonrd、@ollyw、@aymericzip、@davidhu2000、@attilarepka、@devpla、@dydals3440、@huozhi、@wbinnssmith、@suu3、@PapatMayuri、@Sahil4883、@abyii、@molebox、@sokra、@maciej-ka、@abvthecity、@damiensedgwick、@alitas、@RiskyMH、@ytreister、@sommeeeer、@n1ckoates、@yongholeeme、@spidersouris、@gurkerl83、@cassiossantos、@Netail、@tknickman、@eur00t、@cseas、@nnnnoel、@Manoj-M-S、@lfades、@matmannion、@mikeboensel、@nphmuller、@apostolos、@k15a、@pavelee、@locothedev、@vexcat、@Zach-Jaensch、@decepulis、@gadcam、@lukahartwig、@jsanford8、@RobinMalfait、@raunofreiberg、@mohsen1、@skushagra、@amannn、@HQidea、@jrandolf、@smit-err、@littledivy、@k35o、@martinsione、@CvX、@msereniti、@Timer、@Iftee97、@chibicode、@RobPruzan、@PlagueFPS、@bjunix、@maximevtush、@michaelven、@sedlukha、@johannpinson、@AxelUser、@Nayeem-XTREME、@IcaroG、@blurrah、@lachlanjc、@ashi009、@conico974、@raphaelcosta、@dulmandakh、@khuezy、@Knoa0405、@wangsijie、@stefanprobst、@wentsul、@loopy-lim、@bratvanov、@hedgeday 和 @cassian-goode 的贡献！