# Next.js 16 完整指南 ## 目的 Next.js 16 革命性功能的综合参考：具有“使用缓存”功能的缓存组件、作为默认捆绑器的稳定 Turbopack、proxy.ts 架构、DevTools MCP 集成和 React 编译器支持。 ## 何时使用 * 启动新的 Next.js 项目（从第一天开始使用 16 个） * 从 Next.js 15 迁移到 16 * 了解缓存组件和部分预渲染 (PPR) * 配置 Turbopack 以获得最佳性能 * 将 middleware.ts 迁移到 proxy.ts * 通过 DevTools MCP 利用 AI 辅助调试 * 设置 React Compiler 进行自动记忆 ## 更改内容：Next.js 15 → 16 ### 大局观 Next.js 15 是 **过渡阶段** \- 异步 API、实验性 Turbopack、更改缓存默认值。 Next.js 16 是**回报** \ - 一切都变得稳定、快速且可用于生产。 ### 主要差异特色| Next.js 15 | Next.js 16 ---|---|--- **捆绑器** | Webpack（默认）、Turbopack（选择加入测试版）| Turbopack（默认，稳定） **缓存** |隐含的、令人困惑的默认值明确“使用缓存” **网络层** | middleware.ts（边缘运行时）| proxy.ts（Node.js 运行时） **开发工具** |基本错误消息 |用于 AI 调试的 MCP 集成 **反应编译器** |实验|稳定，可投入生产 **性能** |基线|构建速度提高 2-5 倍，快速刷新速度提高 10 倍 ** ** ## 🚀 核心功能（20% 实现 80%） ### 1\.缓存组件+“使用缓存” **Next.js 15 中的问题：** * 隐式缓存很“神奇”——很难预测缓存的内容 * 静态/动态之间的切换不清楚 * 性能优化感觉像是猜测 **Next.js 16 中的解决方案：** // 在 next.config.ts 中启用常量 nextConfig = { 缓存组件：true， }; 导出默认的nextConfig； **使用模式：** // 应用程序/仪表板/page.tsx 从'react'导入{Suspense}； // 该组件缓存其输出异步函数 UserMetrics() { '使用缓存'； // 🎯 显式缓存 const 指标 = 等待 fetchMetrics(); // 缓存结果返回 ; } // 这保持动态异步函数 LiveBalance() { const 余额 = 等待 fetchBalance(); // 永远新鲜返回 ; } 导出默认函数 Dashboard() { 返回（

}> {/* 缓存，即时加载 */} {/* 动态、实时 */}

）； } **为什么这很重要：** * **即时导航** \- 缓存部分立即加载 * **选择性新鲜度** \- 仅按需获取动态部分 * **可预测的行为** \- 您可以控制缓存的内容 * **SaaS 仪表板** \- 非常适合具有混合静态/动态内容的面板 **缓存粒度：** // 缓存整个页面导出默认异步函数 Page() { '使用缓存'；返回<页面内容/>； } // 缓存单个组件异步函数 ExpenseWidget() { '使用缓存'； return <图表数据={await getData()} />; } // 缓存函数结果异步函数 getStats() { '使用缓存'；返回等待数据库.query('...'); } ** ** ### 2\. Turbopack：默认捆绑器（稳定） **性能数据（官方 Vercel 基准）：** * **生产构建速度加快 2-5 倍** * **正在开发中，快速刷新速度提高了 10 倍** * **文件系统缓存** \- 大型项目的重新启动速度更快 **无需配置：** // next.config.ts // Turbopack 现在是默认的 - 无需配置！ **选择退出（如果需要）：** # 使用 Webpack 代替下一个构建--webpack **文件系统缓存（测试版）：** // next.config.ts 常量 nextConfig = { 实验：{ TurbopackFileSystemCacheForDev: true, // 重新启动速度更快 }, }; **为什么这很重要：** * **更快的反馈循环** \- 立即查看更改（快 10 倍） * **更短的 CI/CD 时间** \- 生产构建速度加快 2-5 倍 * **更好的 DX** \- 更少的等待，更多的运输 * **大型项目** \- 比 Webpack 更好的扩展性 **您注意到什么：** # 之前（Webpack） ✓ 4.2s编译 # 之后（Turbopack） ✓ 编译时间为 0.4 秒 # 快 10 倍 ** ** ### 3\. proxy.ts 替换 middleware.ts **变化：** # 旧的 (Next.js 15) middleware.ts # Edge 运行时，令人困惑 # 新 (Next.js 16) proxy.ts # Node.js 运行时，显式 **迁移示例：** // 旧：middleware.ts 从'next/server'导入{NextResponse}；从 'next/server' 导入类型 { NextRequest }；导出函数中间件（请求：NextRequest）{ return NextResponse.redirect(new URL('/home', request.url)); } 导出常量配置= { 匹配器：'/about/:path*', }; // 新：proxy.ts 从'next/server'导入{NextResponse}；从 'next/server' 导入类型 { NextRequest }； export default function proxy(request: NextRequest) { // 更改函数名称 return NextResponse.redirect(new URL('/home', request.url)); } 导出常量配置= { 匹配器：'/about/:path*', }; **主要变化：** 1. 重命名文件： `middleware.ts` → `proxy.ts` 2、重命名export：`导出函数中间件`→`导出默认函数代理` 3.运行时：在Node.js上运行（不是边缘） **为什么这很重要：** * **更清晰的边界** \- “代理” = 网络入口点 * **可预测的运行时间** \- 始终使用 Node.js，没有边缘歧义 * **更好的调试** \- 标准 Node.js 环境 ** ** ### 4\. DevTools MCP（人工智能辅助调试） **它的作用：** Next.js 16 集成了模型上下文协议 (MCP)，因此 AI 代理可以： * 读取统一的浏览器+服务器日志 * 了解 Next.js 路由和缓存 * 自动访问错误堆栈跟踪 * 提供页面感知调试上下文 **为什么这很重要：** * **AI 副驾驶** 可以本地调试您的 Next.js 应用程序 * **更快的调试** \- AI 了解框架内部结构 * **更好的 DX** \- 代理看到您所看到的（以及更多） **使用案例：** 你：“为什么这个页面没有缓存？” AI代理（带有MCP）： - 读取服务器日志 - 查看路线配置 - 检查缓存标头 - 了解 Next.js 16 条缓存规则 →“您的组件中缺少‘使用缓存’指令” **集成：** 自动与 Claude Code、Cursor 和其他 MCP 兼容工具配合使用。 ** ** ### 5\. React 编译器（稳定） **它的作用：** 自动记忆组件 - 不再需要手动 `useMemo`、`useCallback`、`React.memo`。 **设置：** npm 安装 babel-plugin-react-compiler@latest // next.config.ts 常量 nextConfig = { ReactCompiler: true, // 从实验版移至稳定版 }; **之前（手动优化）：** // 你必须在任何地方都这样做 const MemoizedComponent = React.memo(function Component({ data }) { const 已处理 = useMemo(() => processData(data), [data]); const handleClick = useCallback(() => { 控制台.log（已处理）； }, [已处理]); 返回

{processed}

; }); **之后（React 编译器执行此操作）：** // 只需编写代码，编译器自动优化函数组件（{数据}）{ const 已处理 = processData(数据); // 自动记忆 const handleClick = () => { // 自动记忆控制台.log（已处理）； }; 返回

{processed}

; } **为什么这很重要：** * **更少的样板** \- 编写更清晰的代码 * **更好的性能** \- 编译器比手动优化更智能 * **没有错误** \- 编译器永远不会忘记依赖项 ** ** ## 🔥 重大变更 (15 → 16) ### 所需的更改 #### 1\. Node.js 版本 # 最低：Node.js 20.9+ # Next.js 15：Node.js 18 有效 # Next.js 16：不再支持 Node.js 18 #### 2\.异步参数和搜索参数 // ❌ 旧 (Next.js 15) 导出默认函数 Page({ params, searchParams }) { const id = params.id; // 同步 } // ✅ 新 (Next.js 16) 导出默认异步函数 Page({ params, searchParams }) { const { id } = 等待参数； // 必须等待 const { 查询 } = 等待 searchParams; } #### 3\.异步 cookies()、headers()、draftMode() // ❌ 老从'next/headers'导入{cookies}；导出函数 MyComponent() { const token = cookies().get('token'); // 同步 } // ✅ 新从'next/headers'导入{cookies}；导出异步函数 MyComponent() { const cookieStore = 等待 cookies(); // 必须等待 const token = cookieStore.get('token'); } #### 4\. revalidateTag() 现在需要cacheLife配置文件 // ❌ 老 revalidateTag('帖子'); // ✅ 新 revalidateTag('帖子', '最大'); // 选项：“最大”、“小时”、“天” #### 5\.中间件.ts → proxy.ts # 需要迁移 mv middleware.ts proxy.ts # 更新函数名称导出默认函数 proxy(request) { ... } ### 删除的功能 * **AMP 支持** \- 完全删除 * **`下一个 lint` 命令** \- 已删除 * **Node.js 18** \- 不再支持 * **TypeScript <5.1** \- 不再支持 ** ** ## 📦 迁移指南（分步） ### 1\.迁移前检查清单 # 检查当前版本节点 --version # 应该是 20.9+ npm list next # 当前 Next.js 版本 npm list React # React 版本 ### 2\.自动迁移 # 升级到最新的 Next.js 16 npm install next@latest React@latest React-dom@latest # 运行 codemod （自动处理大多数更改） npx @next/codemod@canary 升级最新 ### 3\.手动更改 **更新next.config：** // next.config.ts 从“下一个”导入类型{NextConfig}；常量 nextConfig: NextConfig = { // 启用缓存组件缓存组件：true， // 启用 React 编译器反应编译器：正确， // 可选：文件系统缓存实验：{ TurbopackFileSystemCacheForDev：true， }, }; 导出默认的nextConfig； **重命名中间件：** # 如果你有 middleware.ts git mv middleware.ts proxy.ts # 更新 proxy.ts 中的函数名称导出默认函数代理（请求：NextRequest）{ // 你的逻辑 } **更新异步 API：** // 搜索代码库： // - 参数。 // - 搜索参数。 // - cookie() // - headers() // - 草稿模式() // 在每个之前添加await ### 4\.测试一切 # 开发 npm run dev # 应该自动使用 Turbopack # 生产构建 npm run build # 应该快 2-5 倍 # 运行测试 npm测试 ### 5\.部署 # 验证生产中的 Node.js 版本 # 部署到 Vercel/平台 # 监控前 24 小时内的错误 ** ** ## 🎯 最佳实践 ### 1\.使用 Next.js 启动新项目 16 npx create-next-app@latest my-app # 自动使用 Next.js 16、Turbopack、TypeScript、Tailwind ### 2\.策略性地使用“使用缓存” // ✅ 好：缓存昂贵的、不经常更改的数据异步函数 MonthlyReport() { '使用缓存'；返回等待生成报告（）； } // ❌ 不好：不缓存用户特定的实时数据异步函数 CurrentBalance() { '使用缓存'； // 错误的！这个应该很新鲜返回等待 getUserBalance(); } ### 3\.监控构建性能 # Next.js 16 显示详细时序 npm 运行构建 # 输出示例：路线（应用程序）大小首先加载JS ┌ ○ / 142 B 87.2 kB ├ ○ /_未找到 142 B 87.2 kB └ ○ /仪表板 1.23 kB 88.4 kB 构建时间：14.2 秒 # 在带有 Webpack 的 Next.js 15 中为 57 秒 ### 4\.利用 DevTools MCP * 使用支持 MCP 的 Claude 代码/光标 * 让 AI 代理读取 Next.js 内部结构 * 问：“为什么我的页面很慢？” - 代理查看服务器日志 ### 5\.为大型应用程序启用 React 编译器 // 仅当您遇到性能问题时反应编译器：true ** ** ## 📊 何时升级（决策矩阵） ### ✅ 立即升级如果： * 开始新项目（从第一天开始使用 16） * 小型/中型代码库（<50 条路线） * 使用Vercel（经过测试的平台） * 希望构建速度提高 2-5 倍 * 需要即时导航（缓存组件） ### ⏳ 等待 1-2 周，如果： * 大型生产应用程序（>100 条路线） * 大量使用 middleware.ts（需要 proxy.ts 迁移） * 自定义Webpack配置 * 第三方库尚不兼容 * 规避风险的部署政策 ### 🚫 如果出现以下情况，请勿升级： * 使用 AMP 页面（在 16 中删除） * 卡在 Node.js 18 上（无法升级） * 定制构建管道（需要适配器测试） * 生产中的实验特性 ** ** ## 🔗 资源 * [Next.js 16 发行说明]() * [升级指南]() * [Turbopack 文档]() * [缓存组件指南]() * [Codemod CLI]() ** ** ## 💡 快速参考 ### 安装 npm install next@latest React@latest React-dom@latest ### 启用功能 // next.config.ts 常量 nextConfig = { cacheComponents: true, // 缓存组件 ReactCompiler: true, // React 编译器实验：{ TurbopackFileSystemCacheForDev: true, // 更快的开发重启 }, }; ### 迁移清单 * 安装 Node.js 20.9+ * `npm install next@latest` * 运行 `npx @next/codemod@canary 升级最新版` * 重命名 `middleware.ts` → `proxy.ts` * 将 `await` 添加到 params/searchParams/cookies/headers * 使用cacheLife更新`revalidateTag()`调用 * 测试构建：`npm run build` * 测试开发：`npm run dev` * 首先部署到staging ** ** **总结：** Next.js 16 兑现了 15 的承诺 - 一切都更快、更明确并且可用于生产。 Turbopack 是默认的，缓存是可预测的，AI 工具是原生的。这是 2025 年构建现代 SaaS 应用程序的版本。

Nextjs 16 完整指南

包含技能