Turbopack

Vercel 打造的基于 Rust 的增量式打包器——作为 Webpack 的继任者深度集成于 Next.js，提供毫秒级热更新和数倍于 Webpack 的生产构建速度。

技术简介说明

Turbopack 是由 Tobias Koppers（Webpack 原创作者）加入 Vercel 后主导开发的下一代 JavaScript/TypeScript 增量式打包器，于 2022 年 10 月首次公开发布。它的核心设计理念是"增量计算"（Incremental Computation）：基于 Rust 构建的 Turbo Engine 能够在函数级别缓存计算结果并追踪文件依赖关系，当代码发生变更时，仅重新计算受影响的最小范围，而非重建整个模块图。这一架构从根本上解决了大型应用在开发阶段冷启动慢、HMR 延迟高的核心痛点。

Turbopack 从诞生之初就与 Next.js 深度绑定，采用统一的依赖图（Unified Graph）同时处理客户端和服务端两套运行环境，避免了传统多编译器拼接的复杂性。在开发模式下，Turbopack 采用懒加载打包策略——只打包开发服务器实际请求的模块，显著降低了初始编译时间和内存占用。与 Vite 依赖浏览器原生 ESM 不同，Turbopack 在开发阶段也进行打包，但以高度优化的方式保持大型应用的响应速度。

2025 年 10 月发布的 Next.js 16 正式将 Turbopack 设为默认打包器（dev 和 build 均启用），无需任何额外配置或 --turbopack 标志。截至 2026 年 7 月，Turbopack 已成为 Next.js 生态中事实上的标准打包器，超过 50% 的开发会话和大量生产构建运行在 Turbopack 之上。Vercel 内部所有项目均已切换到 Turbopack，并观察到了显著的开发效率提升。

基本信息

• 官网：https://turbo.build/pack（重定向至 https://turborepo.dev/pack）
• GitHub：https://github.com/vercel/next.js（Turbopack 作为 Next.js 核心模块集成发布）
• License：MIT（随 Next.js 开源）
• 最新版本：随 Next.js 16.3（2026 年）发布；Next.js 当前版本 16.2.10
• 主要维护者/公司：Vercel（Turbopack 团队核心成员包括 Tobias Koppers @sokra、Benjamin Gruenbaum @bgw、Luke & Niklas @mischnic 等）
• 主语言：Rust
• 编译器依赖：SWC（Speedy Web Compiler）
• 平台支持：macOS（x64/ARM64）、Windows（x64/ARM64）、Linux glibc/musl（x64/ARM64）；FreeBSD 等平台回退到 WASM 但不支持 Turbopack
• Node.js 要求：Node.js 20.9+（Next.js 16 起）

快速上手

安装（主要通过 Next.js 使用）

Turbopack 从 Next.js 16 开始是默认打包器，无需额外安装或配置：

# 创建新的 Next.js 项目（默认已使用 Turbopack）
npx create-next-app@latest my-app
cd my-app
 
# 已有项目升级到 Next.js 16
npx @next/codemod@canary upgrade latest
# 或手动升级
npm install next@latest react@latest react-dom@latest

package.json 中的脚本无需修改：

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

如需回退到 Webpack，可使用 --webpack 标志：

next dev --webpack
next build --webpack

基础配置

Turbopack 通过 next.config.js（或 next.config.ts）中的 turbopack 字段进行配置：

// next.config.js
module.exports = {
  turbopack: {
    // 模块路径别名（类似 webpack.resolve.alias）
    resolveAlias: {
      underscore: 'lodash',
      '@components': './src/components',
    },
 
    // 自定义文件扩展名解析
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.json'],
 
    // 配置 webpack 兼容 loader（仅支持返回 JS 的 loader）
    rules: {
      '*.svg': { loaders: ['@svgr/webpack'], as: '*.js' },
    },
 
    // 忽略特定的 Turbopack 错误/警告
    // ignoreIssue: ['some-warning-code'],
  },
 
  // 实验性功能
  experimental: {
    // 开发环境文件系统缓存（Next.js 16.1 起默认开启）
    turbopackFileSystemCacheForDev: true,
 
    // 生产构建文件系统缓存（opt-in）
    turbopackFileSystemCacheForBuild: true,
 
    // 生产环境压缩
    turbopackMinify: true,
 
    // Tree Shaking 增强（module-fragments 模式）
    turbopackTreeShaking: false,
 
    // 移除未使用的导入/导出
    turbopackRemoveUnusedImports: true,
    turbopackRemoveUnusedExports: true,
 
    // Scope Hoisting（生产默认开启）
    turbopackScopeHoisting: true,
  },
}

最小示例

# 1. 创建项目
npx create-next-app@latest turbopack-demo --typescript --tailwind --app
cd turbopack-demo
 
# 2. 启动开发服务器（Turbopack 已默认启用）
npm run dev

终端会显示 Turbopack 编译信息：

   ▲ Next.js 16 (Turbopack)
   - Local:   http://localhost:3000
   - Network: http://192.168.1.100:3000

 ✓ Compiled successfully in 615ms

核心概念与架构

Rust 核心

Turbopack 的核心使用 Rust 编写，利用 Rust 的零成本抽象、内存安全和高并发能力，实现了原生级别的执行效率。相比基于 JavaScript 的 Webpack，Rust 核心带来了数量级的性能提升，特别是在大型项目中的模块解析、依赖分析和代码转换环节。底层使用 SWC（Speedy Web Compiler）作为 JavaScript/TypeScript 的编译引擎，负责语法转换、JSX 编译和代码压缩。

增量计算引擎

Turbopack 的核心创新是其"增量计算"模型。传统打包器在文件变更后需要重新遍历整个模块图，而 Turbopack 在函数级别缓存每一个计算结果，并精确追踪文件之间的依赖关系。当某个文件发生变化时，Turbopack 仅重新计算直接和间接受影响的函数，未受影响的部分直接复用缓存。这使得 HMR 速度在项目规模增长时保持恒定，不会随模块数量增加而显著变慢。

持久化文件系统缓存

从 Next.js 16.1 开始，Turbopack 支持将编译器产物持久化到磁盘，在开发服务器重启或生产构建时跳过未变更模块的重新编译。这一特性在大型项目中尤为关键——首次冷启动后，后续启动的编译时间可减少 50% 以上。Vercel 内部所有项目已启用此功能，观察到大型仓库的开发效率显著提升。

统一依赖图

Next.js 同时面向客户端和服务端两套运行环境（浏览器 + Node.js/Edge），传统方式需要维护多个编译器实例并拼接产物。Turbopack 使用单一的、统一的依赖图处理所有环境，自动完成服务端/客户端组件的正确分包（RSC 场景下尤为关键），消除了多编译器配置的一致性问题。

懒加载打包

Turbopack 在开发模式下仅打包开发服务器实际请求的模块——用户访问某个路由时，只编译该路由所需的模块图，而非整个应用。这种懒加载策略大幅降低了初始编译时间，使千模块级别的应用冷启动也能控制在数秒内。

核心特性

1. 极速 Fast Refresh

Turbopack 提供高达 5-10 倍的 Fast Refresh 速度提升。在万模块级别的项目中，HMR 更新时间稳定在约 50ms，不随项目规模增长而变慢（Webpack 在同等规模下通常需要 1.6 秒以上）。根模块变更约 7ms，叶模块变更约 11ms。

2. 生产构建加速

生产构建速度提升 2-5 倍。Cal.com（Next.js 15.5）的实测数据为 Turbopack 152 秒 vs Webpack 187 秒（快约 19%）；Makerkit（Next.js 16）的实测为 Turbopack 5.7 秒 vs Webpack 24.6 秒（快约 4.3 倍）。

3. 零配置 CSS 支持

内置支持全局 CSS、CSS Modules（基于 Lightning CSS）、CSS 嵌套、@import 语法、PostCSS（Tailwind CSS、Autoprefixer 等）、Sass/SCSS。CSS 处理由 Lightning CSS 驱动，性能远超传统 PostCSS 方案。

4. Babel 自动集成

从 Next.js 16 开始，Turbopack 在检测到 Babel 配置文件时自动启用 Babel 支持（turbopackUseBuiltinBabel）。SWC 仍负责 Next.js 内部转换和语法降级，Babel 用于用户自定义转换。

5. Webpack Loader 兼容

支持使用 webpack loader 的子集（仅支持返回 JavaScript 的 loader），可通过 turbopack.rules 配置自定义文件处理规则。这使得大量现有的 webpack loader 可以在 Turbopack 中复用。

6. React Server Components 原生支持

Turbopack 确保 RSC 场景下服务端和客户端代码的正确分包，是 Next.js App Router 的核心基础设施。支持 React Fast Refresh、JSX/TSX 编译、Server/Client 组件边界识别。

7. Magic Comments

支持 webpack 兼容的魔法注释，包括 webpackIgnore: true（跳过打包）、turbopackIgnore: true（Turbopack 专用跳过）、turbopackOptional: true（抑制解析错误）。适用于动态 import()、require()、require.resolve() 和 new Worker() 表达式。

8. 路径别名与模块解析

自动读取 tsconfig.json 的 paths 和 baseUrl 配置，同时支持通过 resolveAlias 手动设置别名、通过 resolveExtensions 自定义扩展名。与 webpack 的 resolve.alias 行为一致。

9. 多平台原生绑定

提供 macOS、Windows、Linux（glibc/musl）的 x64 和 ARM64 原生绑定。在不支持原生绑定的平台（如 FreeBSD、OpenBSD）上回退到 WASM，但 WASM 模式不支持 Turbopack（需使用 --webpack）。

10. 性能追踪与调试

通过 NEXT_TURBOPACK_TRACING=1 环境变量可生成性能追踪文件（.next/dev/trace-turbopack），用于诊断性能问题和内存泄漏，便于向 Next.js 团队提交诊断信息。

生态图

与 Next.js 的关系

Turbopack 不是一个独立的打包工具，而是作为 Next.js 的内置打包器存在。它没有独立的 CLI 或配置文件，完全通过 Next.js 的配置系统（next.config.js 的 turbopack 字段）进行控制。这意味着 Turbopack 的所有能力都通过 Next.js 暴露，无法脱离 Next.js 独立用于 Vite、Remix、Nuxt 等其他框架。

与 Turborepo 的关系

Turbopack 和 Turborepo 同属 Vercel 的 Turbo 产品线，共享同一网站（turbo.build / turborepo.dev），但职责完全不同：

• Turborepo：Monorepo 构建系统，负责任务编排、远程缓存、并行执行
• Turbopack：JavaScript/TypeScript 打包器，负责模块解析、依赖分析和代码打包

两者在 Vercel 的产品战略中互补——Turborepo 管理多个应用/包的构建流程，Turbopack 加速单个 Next.js 应用的打包过程。

插件生态

Turbopack 不支持 webpack 插件系统（如 DefinePlugin、BundleAnalyzerPlugin、HtmlWebpackPlugin 等），这是一个重大限制。目前仅支持 webpack loader 的子集。对于需要 webpack 插件的场景，用户需要：

1. 寻找 Turbopack 兼容的替代方案
2. 使用 --webpack 标志回退到 Webpack
3. 等待 Vercel 后续扩展 loader/plugin 支持

编译器生态

Turbopack 基于 SWC 进行 JavaScript/TypeScript 编译，CSS 处理基于 Lightning CSS，Sass 使用内置 Rust 实现。PostCSS 在 Node.js worker pool 中运行。这些组件共同构成了 Turbopack 的编译工具链。

适用场景

1. Next.js 中大型应用开发

Turbopack 的核心价值在大型应用中体现最为明显。当项目模块数量达到数千甚至上万时，Webpack 的 HMR 延迟会显著增加（1.6s+），而 Turbopack 的增量计算能保持恒定的 ~50ms 更新速度，极大提升开发体验。

2. 需要频繁迭代的组件开发

Fast Refresh 的速度直接影响"改代码 → 看效果"的循环效率。Turbopack 的 5-10 倍 Fast Refresh 加速让 UI 开发流程更加流畅，减少等待时间。

3. 频繁重启的开发工作流

启用文件系统缓存后，Turbopack 在服务器重启时跳过未变更模块的重新编译。对于需要频繁启动/停止开发服务器的团队（如多人协作、CI 环境），这能显著减少等待时间。

4. 生产构建性能敏感的 CI/CD 流水线

2-5 倍的生产构建速度提升直接缩短 CI/CD 流水线时间。在 Cal.com 等大型应用中，构建时间从 187 秒降至 152 秒，在高频部署场景下累积效果显著。

5. React Server Components 重度使用

Turbopack 对 RSC 的支持是其独有的优势——统一依赖图自动处理服务端/客户端组件的分包边界，这是 Webpack 和 Vite 在 Next.js 中难以匹敌的集成深度。

6. Monorepo 中的 Next.js 应用

结合 Turborepo 的任务编排能力，Turbopack 在 Monorepo 场景下可以提供更快的单个应用开发体验。Turborepo 管理跨包依赖和构建顺序，Turbopack 加速单个 Next.js 应用的打包。

7. 新项目从零开始

新项目没有 webpack 配置包袱，可以直接享受 Turbopack 的零配置体验。Next.js 16 的 create-next-app 默认已使用 Turbopack，无需任何迁移工作。

开发与工程化

开发流程

1. 项目初始化：使用 create-next-app 创建项目，Turbopack 已默认启用
2. 日常开发：运行 next dev，享受毫秒级 Fast Refresh
3. 配置调整：通过 next.config.js 的 turbopack 字段配置别名、loader 等
4. 类型检查：Turbopack 不做类型检查，需配合 tsc --watch 或 IDE 进行
5. 调试：使用 NEXT_TURBOPACK_TRACING=1 next dev 生成性能追踪文件

构建部署

1. 生产构建：运行 next build，Turbopack 默认启用，无需额外配置
2. Webpack 回退：如遇兼容性问题，使用 next build --webpack 回退
3. Vercel 部署：Vercel 平台自动使用 Turbopack，无需手动配置
4. 自建部署：next build && next start，Turbopack 构建产物与 Webpack 一致

最佳实践

• 优先使用 Turbopack：新项目和问题不大的迁移项目优先使用默认打包器
• 渐进式迁移：对于依赖大量 webpack 插件的旧项目，可先用 Turbopack 做开发（next dev），生产构建仍用 Webpack（next build --webpack）
• 启用文件系统缓存：在 next.config.js 中开启 turbopackFileSystemCacheForDev（Next.js 16.1 起默认）和 turbopackFileSystemCacheForBuild
• 利用路径别名：通过 resolveAlias 配置路径别名，保持导入路径简洁
• 避免 webpack 专属语法：新项目尽量避免使用 webpack 特有的插件或 loader，减少未来迁移阻力
• 监控构建时间：Next.js 16 的终端输出会显示每个构建步骤的耗时，便于识别瓶颈

性能与安全

性能特点

开发阶段性能

Turbopack 的核心优势在于 HMR 速度不随项目规模增长而退化——增量计算引擎精确追踪受影响的函数，避免全量重算。冷启动速度略慢于 Vite（Vite 利用浏览器原生 ESM 跳过打包），但远快于 Webpack。

生产构建性能

包体积注意事项

需特别注意的是，Turbopack 的产物包体积在部分场景下可能大于 Webpack。Cal.com 的测试显示：共享客户端 chunk 从 180KB 增长到 391KB（+117%），首屏 JS 增加 279KB（+72%），全部 153 个路由的 JS 体积均大于 Webpack 构建。这是 Turbopack 当前已知的短板，Vercel 团队正在持续优化。

优化建议

• 启用 turbopackTreeShaking 增强 Tree Shaking（实验性 module-fragments 模式）
• 启用 turbopackRemoveUnusedImports 和 turbopackRemoveUnusedExports 移除无用代码
• 启用 turbopackScopeHoisting（生产默认开启）减少模块包装开销
• 启用 turbopackFileSystemCacheForBuild 加速增量生产构建

安全特性

Turbopack 作为打包器，安全性主要体现在以下方面：

• 模块隔离：严格遵循 ES Module 和 CommonJS 的作用域规则，不会意外泄露内部变量
• 路径解析安全：默认限制在项目根目录内解析模块，防止访问项目外的敏感文件（可通过 turbopack.root 显式扩展）
• 无运行时注入：不像 Webpack DefinePlugin 那样支持全局变量注入（Turbopack 不支持 webpack 插件）
• 供应链安全：基于 Rust 的原生绑定减少了 JavaScript 供应链攻击面

技术对比

与 Webpack 对比

与 Vite 对比

与 Rspack 对比

与 Farm 对比

最佳实践

生产环境最佳实践

1. 保持 Next.js 更新：Turbopack 的改进随 Next.js 版本发布，及时更新可获得性能修复和新特性
2. 启用文件系统缓存：在 CI/CD 环境中开启 turbopackFileSystemCacheForBuild，利用缓存加速增量构建
3. 监控包体积：使用 Next.js 16.1 引入的 bundle analyzer 监控包体积变化，注意 Turbopack 的产物可能大于 Webpack
4. Tree Shaking 增强：对包体积敏感的项目可启用实验性的 turbopackTreeShaking（module-fragments 模式）
5. 生产构建验证：部署前使用 next build 验证构建结果，关注构建时间和产物大小

Next.js 集成建议

1. 新项目默认使用 Turbopack：无需任何配置，直接使用 next dev 和 next build
2. 旧项目渐进迁移：
   • 先在开发环境使用 Turbopack（next dev），验证功能正常
   • 再切换到生产构建（next build），对比包体积和构建时间
   • 如遇兼容性问题，使用 --webpack 回退特定环节
3. 处理 webpack 插件依赖：Turbopack 不支持 webpack 插件，需寻找替代方案或保持 Webpack
4. CSS Module 排序注意：Turbopack 按 JS 导入顺序排列 CSS Module，可能与 Webpack 行为略有不同，需通过 @import 显式声明依赖
5. Sass 自定义函数限制：sassOptions.functions 不支持（Rust 无法执行 JS 函数），需使用 Webpack 或改用其他方案
6. Babel 配置自动检测：Next.js 16 起 Turbopack 检测到 Babel 配置文件时自动启用，SWC 仍负责内部转换
7. Yarn PnP 不支持：Turbopack 不支持 Yarn PnP，使用 Yarn 的项目需注意

技术局限与边界

1. 框架锁定——仅支持 Next.js

Turbopack 最大的局限是它不是一个独立的打包工具，完全绑定于 Next.js。无法将 Turbopack 用于 Vite、Remix、Nuxt、SvelteKit 或其他任何框架。如果你需要一个通用的 Rust 打包器，Rspack 或 Farm 是更好的选择。Vercel 曾表示未来可能让 Turbopack 独立使用，但截至目前尚未实现。

2. 不支持 Webpack 插件

Turbopack 完全不支持 webpack 插件系统。这意味着 DefinePlugin、BundleAnalyzerPlugin、HtmlWebpackPlugin、CompressionPlugin 等数千个 webpack 插件都无法使用。仅支持返回 JavaScript 的 webpack loader 子集。对于重度依赖 webpack 插件的项目，迁移成本较高。

3. 不兼容 webpack() 配置

next.config.js 中的 webpack() 配置函数在 Turbopack 模式下不生效。需要迁移到 turbopack 配置字段。对于复杂的自定义 webpack 配置，迁移工作量可能不小。

4. 包体积可能增大

多个实测案例表明，Turbopack 的生产构建产物包体积可能显著大于 Webpack。Cal.com 测试中首屏 JS 增加 72%，所有路由的 JS 体积均大于 Webpack 构建。在对包体积敏感的场景（移动端、弱网环境），这是一个需要认真权衡的因素。

5. 部分 CSS 特性不支持

• 独立的 :local / :global 伪类（仅支持函数形式 :global(...)）
• @value 规则（已被 CSS 变量替代）
• :import / :export ICSS 规则
• composes 跨 .css 文件组合（需改为 .module.css）
• sassOptions.functions 自定义 Sass 函数

6. 不支持 Yarn PnP

Turbopack 不支持 Yarn Plug'n'Play 模式，使用 Yarn PnP 的项目需切换到 node_modules 模式或使用 Webpack。

7. 平台限制

仅支持主流平台的原生绑定（macOS/Windows/Linux 的 x64/ARM64）。在不支持的平台（FreeBSD、OpenBSD 等）上，回退到 WASM 模式但完全不支持 Turbopack，必须使用 --webpack。

8. 生态成熟度

Turbopack 于 2022 年发布，2025 年才在 Next.js 16 中达到稳定。相比 Webpack 十余年的生态积累，Turbopack 的社区资源、第三方集成、问题排查经验仍相对有限。遇到边界问题时，可能需要在 Next.js GitHub 上提交 issue 等待官方响应。

学习资源

官方文档

• Turbopack 官方介绍页（重定向至 turborepo.dev/pack）
• Next.js Turbopack API 参考 — 最全面的功能支持列表和配置说明
• Turbopack 配置参考 — 所有配置选项详解
• Next.js 16 发布公告 — Turbopack 成为默认打包器的官方说明
• Next.js 16.1 发布公告 — 文件系统缓存、Bundle Analyzer 等新特性
• Next.js 16.3 Turbopack 更新 — 编译器性能优化
• Vercel 原始 Turbopack 发布博客 — 2022 年首次发布的技术介绍

教程与深度文章

• Turbopack in 2026: The Complete Guide — 2026 年全面指南，含性能基准和迁移建议
• Turbopack vs Webpack vs Vite 2026: Real Benchmarks — 真实项目基准测试和详细对比
• Next.js 15.5 Ships - Turbopack Production Builds (InfoQ) — Turbopack 生产构建首次可用的报道
• Turbopack in Production With Next.js 15 — 生产环境渐进式采用指南
• Turbopack Production Builds in Next.js — 生产构建实践分享

社区与讨论

• Next.js GitHub Discussions — 官方讨论区，包含大量 Turbopack 使用反馈
• Next.js Discord — 实时社区交流
• Reddit r/nextjs — 社区讨论和实战经验
• Hacker News: Turbopack 发布讨论 — 2022 年首次发布时的社区讨论

视频资源

• Maia Teegarden: Introducing Turbopack — Turbopack 技术架构深度演讲
• Next.js Conf 2025 — Next.js 16 及 Turbopack 稳定版发布演讲

2026 年现状

版本状态

截至 2026 年 7 月，Turbopack 已随 Next.js 16.x 系列全面稳定：

发展趋势

1. Webpack 替代已成事实：Next.js 16 将 Turbopack 设为默认，新项目不再需要 --turbopack 标志。Webpack 退居为 --webpack 回退选项，主要用于兼容遗留配置
2. 性能持续优化：Vercel 团队在每个小版本中持续改进编译速度和包体积。16.3 版本聚焦编译器性能，预计后续版本将进一步缩小与 Webpack 的包体积差距
3. 生态系统逐步成熟：随着 Turbopack 成为 Next.js 默认打包器，第三方工具和库正在加速适配。预计 2026 年下半年，主流 webpack 插件的 Turbopack 替代方案将更加丰富
4. 独立使用仍在规划中：Vercel 曾暗示未来可能让 Turbopack 独立于 Next.js 使用（类似 Rspack 的定位），但截至目前尚未落地。对于非 Next.js 项目，Rspack 和 Farm 仍是更好的 Rust 打包器选择
5. 社区采用率快速攀升：Next.js 16 发布后，超过 50% 的开发会话已运行在 Turbopack 上。生产构建的采用率也在稳步增长，但仍有一部分项目因 webpack 插件依赖或包体积考量而保持 Webpack

是否已替代 Webpack 成为 Next.js 默认？

是的。 自 Next.js 16（2025 年 10 月）起，Turbopack 已正式替代 Webpack 成为 Next.js 的默认打包器。next dev 和 next build 均默认使用 Turbopack，无需任何配置或命令行标志。Webpack 作为可选回退方案保留（--webpack 标志），但 Vercel 的长期方向是全面转向 Turbopack。对于新项目，建议直接使用默认的 Turbopack；对于遗留项目，可根据 webpack 插件依赖情况渐进迁移。