Next.js 15.2 | Next.js 框架

Next.js 15.2 带来了错误调试体验的提升。我们很高兴推出

重新设计的错误 UI 和改进的堆栈追踪：重新设计的调试体验。
流式元数据：异步元数据将不再阻止页面渲染或客户端页面转换。
Turbopack 性能改进：我们对 Turbopack 的性能进行了重大改进。
React View Transitions（实验性）：支持 React 的新实验性 View Transitions API。
Node.js 中间件（实验性）：实验性支持在中间件中使用 Node.js 运行时。

立即升级，或开始使用

终端

# Use the automated upgrade CLI
npx @next/codemod@canary upgrade latest
 
# ...or upgrade manually
npm install next@latest react@latest react-dom@latest
 
# ...or start a new project
npx create-next-app@latest

重新设计的错误 UI 和改进的堆栈追踪

我们很高兴宣布对您在构建应用程序时可能遇到的错误进行视觉和质量改进。让我们一起了解每个改进领域

错误覆盖层

An example of the Next.js error overlay after version 15.2 — Next.js 15.2 版本之后的错误覆盖层示例

我们彻底修改了 Next.js 中错误消息的 UI 和呈现方式，使其更易于理解。新的设计突出了错误的核心细节——例如消息、相关的代码框架和调用堆栈——同时减少了来自库或依赖项代码的噪音。这意味着您可以快速找到问题根源并更快地开始修复。

利用 React 中新引入的 owner stacks 功能，我们现在能够提供更高保真度的问题来源信息。Next.js 现在能够显示负责抛出错误的子组件，跳过不负责创建导致错误的元素的中间元素。

我们还简化了自定义指示器偏好的过程，无需添加额外的配置。

An example of the Next.js dev tools preferences — Next.js 开发工具偏好设置示例

我们在错误覆盖层的底部添加了一个反馈部分，让您可以评价错误消息的帮助程度。您的意见有助于我们了解常见的痛点，并改进错误消息，使调试更容易。

开发指示器

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

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

在编译期间，当在路由之间导航时，您会注意到一个变暗的动画 Next.js 徽标。一旦编译完成并且 React 开始渲染，徽标就会变亮，从而提供应用程序状态的视觉提示。

现在打开开发指示器会显示

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

未来的更新将扩展此菜单以包括

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

这种统一的方法将所有关键开发信息放在一个可访问的位置。我们将根据您的反馈，在未来的版本中继续改进和扩展此功能。

流式元数据

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

这意味着对于许多初始 UI 快速可用的页面，初始绘制仍然因不影响用户视觉效果的数据需求而延迟。我们在 15.2 中改进了这一点，允许在 generateMetadata 完成之前将初始 UI 发送到浏览器。

但是，为了保持与期望元数据在文档 <head> 中可用的机器人和爬虫的兼容性，我们继续延迟向某些机器人用户代理发送 HTML。如果您需要更精细地控制哪些机器人接收此处理，您可以通过 next.config.js 中的 htmlLimitedBots 选项自定义用于为它们提供服务的正则表达式。

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

Turbopack 性能改进

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

我们一直在努力提高 Turbopack 的性能，尤其是在没有持久缓存的场景中。作为此版本的一部分，我们引入了以下增强功能

更快的编译时间：早期采用者报告称，与 Next.js 15.1 相比，访问路由时编译时间最多加快了 57.6%。
内存使用量减少： 对于 vercel.com 应用程序，我们观察到在本地开发期间内存使用量减少了 30%。

通过这些改进，Turbopack 现在在几乎所有情况下都应该比 Webpack 更快。如果您遇到任何 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; // Pre-hashed API key in env
 
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('Forbidden', { status: 403 });
  }
 
  console.log('API key validated');
}
 
export const config = {
  runtime: 'nodejs',
};

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

我们计划借此机会改进和重塑中间件 API。如果您有任何建议或请求，请告知我们。这是社区最需要的请求之一，我们很高兴能有一个解决方案。

即将推出

“use cache”（beta 版）：我们一直在内部试用和稳定 "use cache" 作为一个独立功能。请继续关注后续版本中有关此功能的更多详细信息。了解更多关于 "use cache"。
Turbopack 持久缓存（实验性）：我们一直在 Vercel 内部试用持久缓存，性能得到了积极提升。一旦我们进一步稳定它，我们将在一个功能标志后发布它，以获得更多反馈和测试。

其他更改

[功能] 为 create-next-app 添加 --api 标志以创建仅限 Headless 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 名个人开发者共同努力的成果。此版本由以下人员为您带来：

Next.js 团队： Andrew、 Hendrik、 Janka、 Jiachi、 Jimmy、 Jiwon、 JJ、 Josh、 Jude、 Sam、 Sebastian、 Sebbie、 Wyatt 和 Zack。
Turbopack 团队： Benjamin、 Donny、 Maia、 Niklas、 Tim、 Tobias 和 Will。
Next.js Docs 团队： Delba、 Rich、 Ismael 和 Lee。

非常感谢 @ijjk、@unstubbable、@bgw、@gnoff、@eps1lon、@ztanner、@mischnic、@Marukome0743、@leerob、@gaojude、@lubieowoce、@acdlite、@kdy1、@JamBalaya56562、@creationix、@noreiller、@samcx、@delbaoliveira、@styfle、@abdonrd、@ollyw、@wyattjoh、@devjiwonchoi、@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、@timneutkens、@Manoj-M-S、@lfades、@sebmarkbage、@matmannion、@mikeboensel、@nphmuller、@apostolos、@k15a、@pavelee、@locothedev、@vexcat、@Zach-Jaensch、@decepulis、@gadcam、@lukahartwig、@jsanford8、@RobinMalfait、@raunofreiberg、@mohsen1、@skushagra、@feedthejim、@amannn、@HQidea、@jrandolf、@smit-err、@littledivy、@k35o、@martinsione、@CvX、@msereniti、@Timer、@Iftee97、@chibicode、@RobPruzan、@padmaia、@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 的帮助！