nextjs-turbopack

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 目录下；基本使用无需额外配置。
• Bundle Analyzer（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 代理文档

最佳实践

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