Next.js 15.5 | Next.js 框架

Next.js 15.5 包括 Turbopack 构建的 Beta 版本、稳定的 Node.js 中间件、TypeScript 改进、`next lint` 废弃以及 Next.js 16 的废弃警告。此版本的亮点包括：

Turbopack 构建 (beta)：生产 Turbopack 构建（`next build --turbopack`）现在进入 Beta 阶段
Node.js 中间件 (稳定版)：中间件的 Node.js 运行时支持现已稳定
TypeScript 改进：类型化路由、路由导出验证和路由类型助手
`next lint`：废弃 `next lint` 命令
Next.js 16：Next.js 16 的废弃警告

立即升级，或开始使用

# 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

Turbopack 构建 (beta)

我们很高兴地宣布 `next build --turbopack` 进入 Beta 阶段。Turbopack 现在为包括 vercel.com、v0.app 和 nextjs.org 在内的 Vercel 网站提供支持，通过更快的预览和生产部署构建加速迭代速度。

自推出以来，这些由 Turbopack 驱动的应用程序已经过实战检验，处理了超过 12 亿 次请求。

性能与生产结果

Turbopack 的最初设计目标之一是能够帮助开发者随着应用程序和代码库的增长而扩展构建性能。为了实现这一点，Turbopack 从头开始设计，以便在构建的所有阶段都利用多个 CPU 核心。

我们已在许多 Vercel 产品中部署了使用 Turbopack 的构建，并看到了编译时间的持续改进

客户网站：在 4 核机器上速度快 2 倍
客户网站：在 14 核机器上速度快 2.2 倍
小型网站（10K 模块）：在 30 核机器上速度快 4 倍
中型网站（40K 模块）：在 30 核机器上速度快 2.5 倍
大型网站（70K 模块）：在 30 核机器上速度快 5 倍

在我们将 Turbopack 推向主要 Web 应用程序时，我们密切监控了生产性能退化和故障。

与 Webpack 相比，我们的生产指标监控显示，使用 Turbopack 构建的网站在更少的请求中提供相似或更少量的 JavaScript 和 CSS，从而实现了可比或更好的 FCP、LCP 和 TTFB 指标。

对于已在开发中采用 Turbopack 的团队，我们现在建议尝试使用 Turbopack 进行构建。

已知差异

小型项目：在较小的机器或小型项目上，由于 Webpack 内置的持久缓存，我们测得构建时间有了微小或中性的改进。我们目前正在为 Turbopack 开发一个持久缓存解决方案，以实现我们设计目标：使所有构建都是增量且快速的。

打包优化：在某些极端情况下，我们测得 Webpack 生成的包更优化。我们正在跟踪这些情况，并努力在稳定版本发布前缩小差距。有关更多信息，请参阅包大小文档。

CSS 排序：由于 Turbopack 中对副作用处理的启发式方法不同，CSS 文件可能以与 webpack 不同的顺序连接，从而导致潜在的视觉差异。有关更详细的解释和建议的解决方案，请参阅文档。

注意：这些差异已记录，我们正在积极改进。有关详细信息和解决方案，请参阅我们的 Turbopack 文档。

在我们向稳定版本迭代时，请在 GitHub 上报告任何问题。

Node.js 中间件 (稳定版)

在我们的 15.2 版本中引入了对 Node.js 运行时的实验性支持并在我们的生产应用程序上进行了广泛测试后，我们很高兴地宣布稳定支持 Node.js 中间件运行时。

以前，Next.js 中间件仅支持 Edge Runtime，它提供了更好的性能和隔离，但在与 Node.js 特定的库和 API 集成时存在限制。

import { NextRequest, NextResponse } from 'next/server';
 
export const config = {
  runtime: 'nodejs', // Now stable!
};
 
export function middleware(request: NextRequest) {
  // Access to full Node.js APIs and npm packages
  const fs = require('fs');
  const crypto = require('crypto');
 
  // Complex authentication logic
  const token = request.headers.get('authorization');
 
  if (!isValidToken(token)) {
    return NextResponse.redirect(new URL('/login', request.url));
  }
 
  return NextResponse.next();
}
 
function isValidToken(token: string | null): boolean {
  // Use Node.js crypto for validation
  // Access file system, databases, etc.
  return true;
}

此更改使中间件能够处理更复杂的用例，同时保持相同的开发人员体验。

尽管 Node.js 运行时在 Next.js 16 中不会是默认设置，但我们正在探索根据社区反馈和使用模式，在 Next.js 17 中将其作为默认设置。

TypeScript 改进

Next.js 15.5 为 App Router 带来了重大的 TypeScript 改进，具有完整的 Turbopack 兼容性和路由的全面类型安全。

类型化路由 (稳定版)

类型化路由为您的应用程序路由提供编译时类型安全，在它们到达生产环境之前捕获无效链接。此功能根据您的文件结构自动生成类型，确保每个 `<Link>` 组件都指向一个有效的路由。

此功能在 `typedRoutes` 标志后可用，该标志以前是实验性的，现在已稳定。静态类型路由现在通过新的实现与 Turbopack 配合使用，该实现为 Webpack 和 Turbopack 构建提供了类型安全

const nextConfig = {
  typedRoutes: true, // Now stable!
};
 
export default nextConfig;

import Link from 'next/link'
 
// Full type safety for route paths
<Link href="/blog/example-slug?ui=dark">Read Post</Link>
 
// TypeScript catches invalid routes at compile time
<Link href="/invalid-route">Broken Link</Link> // ← Type error

路由导出验证 (Turbopack)

路由导出验证也通过一个新系统在 Turbopack 上工作，该系统生成一个类型保护文件，使用 TypeScript 的 `satisfies` 运算符验证页面、布局和路由处理程序。

这在运行 `next build` 时，在编译期间捕获无效导出（例如不正确的 `dynamic` 值），用更高效的解决方案取代了旧的 Webpack 插件，该解决方案适用于这两种构建系统。

路由属性助手

Next.js 自动生成全局可用的 `PageProps`、`LayoutProps` 和 `RouteContext` 类型，具有完整的参数类型，无需导入

之前：手动类型化和导入

import { Metadata } from 'next';
 
interface Props {
  params: Promise<{ slug: string }>;
  children: React.ReactNode;
  analytics: React.ReactNode; // Manual parallel route typing
  team: React.ReactNode; // Manual parallel route typing
}
 
export default function DashboardLayout(props: Props) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* No type safety for parallel routes */}
      {props.team} {/* No type safety for parallel routes */}
    </div>
  );
}

之后：自动类型化，支持并行路由

// No need to import LayoutProps - globally available
export default function DashboardLayout(props: LayoutProps<'/dashboard'>) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* Fully typed parallel route slot */}
      {props.team} {/* Fully typed parallel route slot */}
    </div>
  );
}

该系统根据您的文件结构自动发现路由，支持动态路由、并行路由和 `next.config.js` 中的自定义路由。类型生成在开发和构建模式下运行，当您的文件结构在开发中发生更改时会立即重新生成类型，并通过仅生成少量优化文件而不是旧实现中使用的许多单个文件来高效扩展到大型项目。

`next typegen`

我们添加了 `next typegen` 命令，用于在不运行 `next dev` 或 `next build` 的情况下手动生成类型。这对于外部类型验证场景特别有用。

next typegen [directory]

以前，路由类型只在 next dev 或 next build 期间生成，这意味着直接运行 tsc --noEmit 不会验证你的路由类型。现在你可以独立生成类型并在外部验证它们。

# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit
 
# Or in CI workflows for type checking without building
next typegen && npm run type-check

`next lint` 废弃

从 Next.js 15.5 开始，`next lint` 命令会显示废弃警告，并将在 Next.js 16 中移除。这通过过渡到明确的 ESLint 配置并引入 Biome 作为快速替代方案，使 linting 体验现代化。

创建新的 Next.js 项目时，您现在可以选择 ESLint（全面的规则）、Biome（规则较少且速度快）或不使用 linter。ESLint 项目现在生成明确的 `eslint.config.mjs` 文件，而不是依赖 `next lint` 命令包装器，从而为您提供 linting 规则的完全透明性。

Biome 项目收到优化的配置，包含 Next.js 和 React 规则以及内置格式化功能。生成的 `package.json` 脚本现在直接调用 linters

{
  "scripts": {
    // ESLint projects
    "lint": "eslint", // Instead of "next lint"
    "lint:fix": "eslint --fix",
 
    // For Biome projects
    "lint": "biome check",
    "format": "biome format --write"
  }
}

对于现有项目，新的 codemod 自动将 `next lint` 迁移到 ESLint CLI

npx @next/codemod@latest next-lint-to-eslint-cli .

codemod 智能地转换 `package.json` 脚本，同时保留功能，将 Next.js 特定标志（如 `--strict`）映射到 `--max-warnings 0`，并自动安装所需的依赖项。

这种过渡使开发人员可以直接控制其 linting 设置，并具有更好的生态系统兼容性。

注意：如果存在 ESLint 配置，`next build` 仍将运行 linting 验证步骤。此构建期间的自动 linting 也将在 Next.js 16 中移除，让您可以完全控制 linting 运行的时间和方式。

Next.js 16 的废弃警告

Next.js 15.5 引入了废弃警告，以帮助您为即将发布的 Next.js 16 版本做准备。这些警告会出现在开发和构建日志中，让您有时间在这些功能被移除之前进行迁移。

`next/link` 的 `legacyBehavior`

next/link 的 legacyBehavior 属性将在 Next.js 16 中移除。此属性在 Next.js 12 到 13 过渡期间作为临时兼容层引入。

// ❌ Will be removed in Next.js 16
<Link href="/about" legacyBehavior>
  <a>About</a>
</Link>
 
// ✅ Modern approach (no changes needed)
<Link href="/about">About</Link>

迁移：移除 `legacyBehavior` 属性和任何子 `<a>` 元素。`Link` 组件现在自动处理样式和可访问性。

AMP 支持

Next.js 的 AMP 支持将在 Next.js 16 中移除。AMP 的采用率显著下降，维护此功能增加了框架的复杂性。所有与 AMP 相关的 API 和配置都将被移除。

// ❌ Will be removed in Next.js 16
import { useAmp } from 'next/amp';
 
export const config = { amp: true };
 
export default function AmpPage() {
  const isAmp = useAmp();
  return <div>AMP Page: {isAmp ? 'AMP' : 'HTML'}</div>;
}

const nextConfig = {
  amp: {
    // ❌ Will be removed in Next.js 16
    canonicalBase: 'https://example.com',
  },
};
 
export default nextConfig;

迁移：移除所有与 AMP 相关的代码，包括

页面中的 `export const config = { amp: true }`
next.config.ts 中的 amp 配置
next/amp 钩子导入和使用（useAmp）
任何其他 AMP 特定 API

评估 AMP 是否仍然是您的用例所必需的。大多数性能优势现在可以通过 Next.js 的内置优化和现代网络标准实现。

`next/image` 质量设置

从 Next.js 16 开始，quality 属性将默认限制为 75。目前在 Next.js 15 中，您可以使用 1 到 100 之间的任何整数，但 Next.js 16 将要求对除 75 之外的质量进行明确配置。

// ⚠️ Will show deprecation warning in Next.js 15.5
// when images.qualities is undefined and quality !== 75
<Image src="/photo.jpg" quality={100} alt="Photo" />
 
// ✅ Explicit configuration required for Next.js 16

const nextConfig = {
  images: {
    qualities: [75, 100], // Explicitly allow quality={100}
  },
};
 
export default nextConfig;

迁移：如果您使用除 75 以外的 quality 属性，请在 next.config.ts 中明确配置 images.qualities，以包含 Next.js 16 所需的质量值。

`next/image` 本地模式

从 Next.js 16 开始，在本地图片 `src` 路径中使用查询字符串将需要 `images.localPatterns` 中的明确配置。这会影响带有查询参数（如缓存清除或版本控制）的图片。

// ⚠️ Will show deprecation warning in Next.js 15.5
// when images.localPatterns is not configured
<Image src="/photo.jpg?v=1" alt="Test" />
 
// ✅ Explicit configuration required for Next.js 16

const nextConfig = {
  images: {
    localPatterns: [
      {
        pathname: '/photo.jpg', // allow exact path
        // omitting "search" will allow all query parameters
      },
      {
        pathname: '/photo.jpg', // allow exact path
        search: '?v=1', // allow exact query parameters
      },
      {
        pathname: '/assets/**', // allow wildcard path
        search: '', // empty search will block all query parameters
      },
    ],
  },
};
 
export default nextConfig;

迁移：在您的 `next.config.ts` 中配置 `images.localPatterns` 以明确允许在您的图片路径中使用查询字符串。这提供了更好的安全性和性能优化。

时间线

这些废弃警告将从 Next.js 15.5 开始出现。这些功能将在 Next.js 16 中完全移除。我们建议尽快迁移，以避免升级过程中出现问题。

分享您的反馈，帮助塑造 Next.js 的未来

贡献者

Next.js 是超过 3,000 名独立开发者共同努力的成果。此版本由以下团队提供

Next.js 团队：Andrew, Ben, Hendrik, Janka, Jiachi, Jimmy, Jiwon, JJ, Josh, Jude, Rob, Sam, Sebastian, Sebbie, Wyatt, 和 Zack。
Turbopack 团队：Benjamin, Josh, Luke, Maia, Niklas, Tim, Tobias, 和 Will。
Next.js 文档 团队：Delba, Rich, Ismael, Joseph, 和 Lee。

衷心感谢 @unstubbable、@gnoff、@RobPruzan、@mischnic、@huozhi、@delbaoliveira、@styfle、@ankur-arch、@skt-t1-byungi、@ijjk、@Han5991、@SyMind、@Anas-github-acc、@hf、@bgw、@wyattjoh、@ztanner、@prateekkish、@eps1lon、@lubieowoce、@timneutkens、@acdlite、@lukesandberg、@bgub、@Cy-Tek、@padmaia、@raunofreiberg、@devjiwonchoi、@sokra、@MidnightDesign、@stephenliang、@allenzhou101、@icyJoseph、@gaojude、@remcohaszing、@wesjune、@wbinnssmith、@m1abdullahh、@Sayakie、@startracex、@chadfennell、@dlehmhus、@Jarred-Sumner、@candymask0712、@stepan662、@PuppyOne、@huperniketes、@xusd320、@MichalMoravik、@fireairforce、@kitfoster、@feedthejim 和 @r34son 的帮助！