Next.js 15.5 带来 Turbopack Beta、Node 中间件稳定与 TypeScript 强化 🚀🚀🚀

最近在出一个前端的体系课程，里面的内容非常详细，如果你感兴趣，可以加我 v 进行联系 yunmz777:

浪费你几秒钟时间，内容正式开始

Next.js 在 React 全栈开发生态中扮演核心角色，早在 2024 年发布的 Next.js 15 中，就引入了 Rust 驱动的 Turbopack 打包器（Turbopack）作为 Webpack 的现代替代方案，同时支持 React 19、异步 Request APIs 等核心特性。

后续的 15.4 版本进一步推进了 Turbopack 的稳定性，已通过全部 8,298 个集成测试并被用于 vercel.com 等高流量站点。

而 15.5 则继续推进这一方向，整体朝着 Turbopack 成为默认构建工具的目标迈进。

如果你想升级，你可以执行如下命令来进行升级：

bash 复制代码

# 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 阶段，现已应用于多个 Vercel 官网站点（包括 vercel.com、v0.app、nextjs.org 等），在预览与生产构建中显著提高了迭代效率。这些站点自上线以来，已累计处理了超过 12 亿次请求，展现出 Turbopack 的生产能力。

性能与生产表现

Turbopack 的设计宗旨之一，就是即使面对日益增长的项目规模，也能保持极致的构建性能。因此，它自底层架构起就全面支持多核 CPU 并行执行各阶段任务。

真实环境测试数据显示，使用 Turbopack 构建时对比 Webpack 构建时间有显著提升：

客户站点：4 核机器提升约 2 倍
客户站点：14 核机器提升约 2.2 倍
小型站点（1 万模块）：30 核机器提升约 4 倍
中型站点（4 万模块）：30 核机器提升约 2.5 倍
大型站点（7 万模块）：30 核机器提升约 5 倍

更重要的是，在生产环境中对比 Webpack 构建，Turbopack 构建的站点 JavaScript 和 CSS 资源体积不增反减、请求次数减少，同时 FCP、LCP、TTFB 等核心性能指标表现更优或相当。

目前，开发者团队强烈建议已在开发流程中引入 Turbopack 的项目，也将其用于构建流程以享受性能提升。

已知差异与注意事项

尽管优势明显，但 Turbopack 在与 Webpack 的对比中，也展现出一些差异与局限：

小型项目：在硬件资源有限或项目规模较小时，构建时间提升可能不明显，甚至差异不大。这主要是因为 Webpack 的磁盘持久缓存机制发挥了优势。目前，官方正在为 Turbopack 推出持久缓存方案，以实现真正的增量与快速构建。
打包优化：在某些极端边缘场景下，Webpack 打包出的 bundle 体积可能更小、更优化。官方团队正在追踪这些情况，并力图在稳定版中缩小差距。相关细节可参考官方 "包大小优化" 文档。
CSS 顺序差异：Turbopack 与 Webpack 对 CSS 副作用的处理策略不同，可能导致 CSS 文件的拼接顺序出现差异，从而带来视觉上的细微不同。针对这一问题，官方文档提供了解释与推荐的解决方案。

总结建议

项目类型	建议
大中型项目	强烈推荐使用 Turbopack 构建，可显著提升性能与迭代效率。
小型项目	若提升有限，可继续使用 Webpack；建议关注 Turbopack 持久缓存功能的发展。
视觉兼容	若发现样式差异，请参考文档提供的解决方案调整 CSS 拼接顺序。
打包体积	如 bundle 体积偏大或优化不理想，可结合 bundle 分析工具对比后选择最佳方案。

Node.js 中间件进入稳定版

在 15.2 版本中，Next.js 首次引入了 Node.js 运行时中间件的实验性支持，并在生产环境中进行了大量测试。如今，这一特性已升级为稳定支持，开发者可以放心在项目中使用。

在此之前，Next.js 中间件仅支持 Edge Runtime。虽然 Edge Runtime 在性能和隔离性方面表现更优，但在集成某些 Node.js 专属库与 API 时存在限制。

如下代码所示：

ts 复制代码

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;
}

这一变化使中间件能够应对更加复杂的使用场景，同时依然保持了原有的开发体验。

需要注意的是，Next.js 16 中 Node.js 运行时并不会作为默认选项。不过，团队正在根据社区反馈与实际使用情况，评估在 Next.js 17 中将其设为默认运行时的可能性。

TypeScript 改进

Next.js 15.5 在 App Router 上带来了重要的 TypeScript 增强：全面支持 Turbopack，并为路由提供了更强的类型安全保障。

1. Typed Routes（稳定版）

Typed Routes 为应用路由提供编译期的类型安全，能够在构建阶段捕获无效的链接，避免错误代码进入生产环境。它会基于文件目录自动生成类型，确保所有 <Link> 组件都指向有效路由。

此前需要通过实验性 typedRoutes 标志启用，而在 15.5 中已成为稳定特性，并且在 Webpack 与 Turbopack 下均可使用。

ts 复制代码

// next.config.ts
const nextConfig = {
  typedRoutes: true, // 已稳定
};
export default nextConfig;

import Link from 'next/link'

// 完整类型安全
<Link href="/blog/example-slug?ui=dark">Read Post</Link>

// 错误路径会在编译时报错
<Link href="/invalid-route">Broken Link</Link> // ← 类型错误

2. Route Export Validation（Turbopack）

在 Turbopack 中，Next.js 通过生成类型守卫文件来校验页面、布局和路由处理器的导出是否符合规范。它利用 TypeScript 的 satisfies 操作符，在运行 next build 时捕获错误导出（例如动态参数配置错误），替代了旧的 Webpack 插件，并且性能更高。

3. Route Props Helpers

Next.js 会自动生成全局可用的 PageProps、LayoutProps、RouteContext 类型，无需手动导入，也能获得完整的参数推导：

以前：需要手写类型和导入

ts 复制代码

import { Metadata } from "next";

interface Props {
  params: Promise<{ slug: string }>;
  children: React.ReactNode;
  analytics: React.ReactNode; // 并行路由需要手动写类型
  team: React.ReactNode; // 并行路由需要手动写类型
}

export default function DashboardLayout(props: Props) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* 没有类型安全 */}
      {props.team} {/* 没有类型安全 */}
    </div>
  );
}

现在：自动生成类型 + 支持并行路由

ts 复制代码

// 不再需要手动导入 LayoutProps
export default function DashboardLayout(props: LayoutProps<"/dashboard">) {
  return (
    <div>
      {props.children}
      {props.analytics} {/* 已有完整类型 */}
      {props.team} {/* 已有完整类型 */}
    </div>
  );
}

该系统会自动发现文件目录中的路由，支持动态路由、并行路由、自定义路由（来自 next.config.js）。在开发和构建阶段都会生成类型，并能在开发时实时更新。相比旧实现，它只生成少量优化文件，而不是为每个路由生成单独的文件，更加高效，尤其适合大型项目。

`next typegen` 命令

新增了 next typegen 命令，用于手动生成路由类型，无需运行 next dev 或 next build。在需要单独做类型验证（如 CI 流程）时非常有用：

bash 复制代码

# 生成类型后再进行 TypeScript 校验
next typegen && tsc --noEmit

# 在 CI 中执行类型检查而不必完整构建
next typegen && npm run type-check

过去，路由类型只有在运行 next dev 或 next build 时才会生成，导致 tsc --noEmit 无法校验路由。现在可以独立生成类型并在外部校验。

`next lint` 弃用

从 Next.js 15.5 开始，next lint 命令会显示弃用警告，并将在 Next.js 16 被移除。这次变更旨在让开发者直接使用显式 ESLint 配置，并提供 Biome 作为更快的替代选项，从而实现更现代化的 lint 流程。

新项目创建时的选择

ESLint：规则全面，适合复杂项目。
Biome：速度快，但规则较少，自带格式化功能。
无 Linter：开发者自行选择工具链。

生成的脚手架将包含显式配置文件：

ESLint 项目生成 eslint.config.mjs；
Biome 项目包含 Next.js 与 React 的优化规则。

并且 package.json 的脚本会直接调用 ESLint 或 Biome：

json 复制代码

{
  "scripts": {
    // ESLint 项目
    "lint": "eslint", // 不再是 "next lint"
    "lint:fix": "eslint --fix",

    // Biome 项目
    "lint": "biome check",
    "format": "biome format --write"
  }
}

迁移现有项目

为方便迁移，官方提供了 codemod 工具：

bash 复制代码

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

它会自动将 package.json 中的脚本从 next lint 转换为 ESLint CLI，并保留原有功能：

--strict → --max-warnings 0
自动安装依赖

这样，开发者能够直接掌控 lint 配置，同时与更广泛的生态保持兼容。

值得注意的是，如果项目中存在 ESLint 配置，next build 仍会运行一次 lint 校验。但这一自动 lint 步骤也会在 Next.js 16 移除，届时开发者可以完全自主决定何时、如何运行 lint。

Next.js 16 弃用警告

Next.js 15.5 引入了弃用警告，帮助开发者提前为即将到来的 Next.js 16 做好迁移准备。这些警告会出现在开发与构建日志中，留给你充足的时间在功能被移除前完成调整。

1. `legacyBehavior`（`next/link`）

next/link 的 legacyBehavior 属性将在 Next.js 16 中被移除。该属性最初是在 Next.js 12 → 13 过渡期间，用于兼容旧版 <a> 包裹写法的临时方案。

tsx 复制代码

// 将在 Next.js 16 移除
<Link href="/about" legacyBehavior>
  <a>About</a>
</Link>

// 推荐写法（现代方式，无需 <a>）
<Link href="/about">About</Link>

迁移方式：删除 legacyBehavior 属性以及子 <a> 元素。

现在 Link 组件已默认处理可访问性和样式，无需额外标签。

2. AMP 支持

Next.js 16 将彻底移除 AMP 支持。由于 AMP 的行业采用率显著下降，继续维护该功能只会增加框架复杂度，因此 AMP 相关的 API 与配置将被删除。

tsx 复制代码

// 将在 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>;
}

ts 复制代码

// next.config.ts 中的配置也将被移除
const nextConfig = {
  amp: {
    canonicalBase: "https://example.com",
  },
};
export default nextConfig;

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

页面中的 export const config = { amp: true }
next.config.ts 中的 AMP 配置
useAmp 以及其他 AMP 专属 API

建议：如果之前依赖 AMP 提升性能，可以转向 Next.js 内置优化能力和现代 Web 标准（如 Image 优化、RSC、Edge 渲染），几乎可以实现同等甚至更好的性能收益。

3. `next/image` 的 `quality` 配置

从 Next.js 16 开始，<Image> 的 quality 属性默认只能使用 75。在 Next.js 15 中仍可设置 1--100 的任意整数，但若想在 16 中使用其他值，需要在配置文件里显式声明允许范围。

tsx 复制代码

// Next.js 15.5 会警告：quality ≠ 75 且未配置 qualities
<Image src="/photo.jpg" quality={100} alt="Photo" />;

// Next.js 16 推荐配置
// next.config.ts
const nextConfig = {
  images: {
    qualities: [75, 100], // 明确允许 100
  },
};
export default nextConfig;

迁移方式：如果项目中使用了 quality ≠ 75 的值，请在 next.config.ts 的 images.qualities 中显式声明需要的质量参数。

4. `next/image` 本地图片 + 查询参数

从 Next.js 16 开始，本地图片路径若带有查询参数（例如 ?v=1 用于版本控制或 cache-busting），必须在 images.localPatterns 中显式允许。

tsx 复制代码

// Next.js 15.5 会警告：未配置 localPatterns
<Image src="/photo.jpg?v=1" alt="Test" />

ts 复制代码

// Next.js 16 推荐配置
// next.config.ts
const nextConfig = {
  images: {
    localPatterns: [
      {
        pathname: "/photo.jpg", // 允许该路径
        // 不写 search → 允许任意查询参数
      },
      {
        pathname: "/photo.jpg",
        search: "?v=1", // 仅允许指定查询参数
      },
      {
        pathname: "/assets/", // 支持通配符
        search: "", // 空字符串 = 禁止所有查询参数
      },
    ],
  },
};
export default nextConfig;

迁移方式：在 next.config.ts 的 images.localPatterns 中，显式声明允许哪些路径和查询参数。这不仅提升了安全性，也有助于框架在构建时更好地进行性能优化。

额外补充

在 Reddit 社区上，有用户分享升级经验：

"对于一个小型博客模板，使用 codemod 升级用了不到 5 分钟，而且 Turbopack 提升立竿见影------原本加载 5 秒的页面现在不到 1 秒。" "但在大项目里，codemod 更新了 30--40 个文件，却遇到了与 React 19 的兼容问题。"

这说明 Turbopack 与 React 19 的性能提升确实明显，但升级过程中可能面临依赖兼容问题，建议在迁移前进行依赖审查与分步测试。

总结

Next.js 15.5 在 App Router 上强化了 TypeScript 支持，对 Turbopack 实现了完整兼容，同时通过 Typed Routes 和 Route Props Helpers 提供了更全面的类型安全。与此同时，next lint 命令遭弃用，项目迁移至显式 ESLint 或更轻量的 Biome 工具成为新趋势。官方也在开发环境和构建日志中引入了多个针对 Next.js 16 的弃用警告，帮助开发者提前适应即将移除的功能。

Next.js 15.5 带来 Turbopack Beta、Node 中间件稳定与 TypeScript 强化 🚀🚀🚀

Turbopack 构建（Beta）：更快、更稳定、更广泛

性能与生产表现

已知差异与注意事项

总结建议

Node.js 中间件进入稳定版

TypeScript 改进

1. Typed Routes（稳定版）

2. Route Export Validation（Turbopack）

3. Route Props Helpers

以前：需要手写类型和导入

现在：自动生成类型 + 支持并行路由

next typegen 命令

next lint 弃用

新项目创建时的选择

迁移现有项目

Next.js 16 弃用警告

1. legacyBehavior（next/link）

2. AMP 支持

3. next/image 的 quality 配置

4. next/image 本地图片 + 查询参数

额外补充

总结

`next typegen` 命令

`next lint` 弃用

1. `legacyBehavior`（`next/link`）

3. `next/image` 的 `quality` 配置

4. `next/image` 本地图片 + 查询参数