Communitygithub.com

junksidetm/darkside-toolkit

Next.js 16+ 与 Turbopack 使用指南 — 增量式 Rust 打包、文件系统缓存、更快的开发启动与 HMR、Turbopack 与 webpack 的权衡,以及 middleware.ts 到 proxy.ts 的文件名变更。适用于开发或调试 Next.js 16+ 应用、诊断开发启动慢或热重载问题、选择打包器,或检查中间件/代理文件命名。

darkside-toolkit 是什么?

该技能旨在指导开发者使用 Next.js 16+ 中的默认打包器 Turbopack。它解释了 Turbopack 如何通过 Rust 实现的增量打包和文件系统缓存,显著提升开发启动速度与热模块替换(HMR),尤其适用于大型项目。技能涵盖了何时使用 Turbopack(默认开发模式)与何时回退到 webpack(遇到 Bug 或依赖 webpack 专属插件时),以及生产构建的行为差异。此外,还重点说明了 Next.js 16 中中间件文件名从 `middleware.ts` 变更为 `proxy.ts` 的细节,避免开发者误判。支持平台包括所有使用 Next.js 16+ 的开发环境(如 Claude Code、Cursor、Codex 等),通过清晰的命令示例和最佳实践帮助优化开发流程与生产包体积。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/junksidetm/darkside-toolkit/tree/HEAD/skills/nextjs-turbopack

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Next.js 与 Turbopack

Next.js 16+ 默认使用 Turbopack 进行本地开发:这是一个用 Rust 编写的增量打包器,可大幅提升开发启动速度和热更新效率。

何时使用

  • Turbopack(默认开发模式):日常开发使用。冷启动和 HMR 更快,尤其在大型项目中。
  • Webpack(传统开发模式):仅在遇到 Turbopack 错误或在开发中依赖仅 webpack 支持的插件时使用。可通过 --webpack(或 --no-turbopack,具体取决于你的 Next.js 版本;请查阅对应版本的文档)禁用。
  • 生产构建:next build 可能使用 Turbopack 或 webpack,取决于 Next.js 版本;请参照官方文档。

适用场景:开发或调试 Next.js 16+ 应用,诊断开发启动慢或 HMR 问题,或优化生产包体积。

工作原理

  • Turbopack:Next.js 开发的增量打包器。利用文件系统缓存,重启速度大幅提升(例如,大型项目可提升 5–14 倍)。
  • 开发默认:从 Next.js 16 开始,next dev 默认使用 Turbopack,除非显式禁用。
  • 文件系统缓存:重启复用先前的工作;缓存通常位于 .next 目录下;基本使用无需额外配置。
  • 包分析器(Next.js 16.1+):实验性 Bundle Analyzer,用于检查输出并找出大型依赖;通过配置或实验性标志启用(详见版本对应的 Next.js 文档)。

示例

命令

next dev
next build
next start

使用

运行 next dev 进行使用 Turbopack 的本地开发。使用 Bundle Analyzer(参见 Next.js 文档)优化代码拆分并削减大型依赖。优先使用 App Router 和服务器组件。

中间件文件命名

Next.js 16 引入了 proxy.ts 作为中间件文件名,取代了旧的 middleware.ts 约定:

  • Next.js 16+:在项目根目录使用 proxy.ts
  • Next.js 16 之前:在项目根目录使用 middleware.ts

文件名变更与 Next.js 版本 相关,而与使用的打包器(Turbopack 或 webpack)无关。请始终参考你所使用的版本的官方文档。

在 Next.js 16 项目中,不要将 proxy.ts 标记为命名错误或缺失的中间件文件。 该文件使用正确且是故意的。建议重命名为 middleware.ts 会破坏中间件执行。

参考:Next.js proxy 文档

最佳实践

  • 保持使用最新的 Next.js 16.x,以获得稳定的 Turbopack 和缓存行为。
  • 如果开发速度慢,请确保使用 Turbopack(默认)且未不必要地清除了缓存。
  • 对于生产包体积问题,请使用你版本对应的官方 Next.js 包分析工具。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能