29. Turbopack 深入

从 Webpack 到 Turbopack

Next.js 16 最大的变化之一，就是 Turbopack 成为默认打包工具。以前你需要手动加 --turbopack 标志，现在直接 next dev 或 next build 就是 Turbopack。

Turbopack 用 Rust 编写，最大的优势是速度。它只打包真正需要的模块，而不是整个应用。对于大型项目，开发服务器的启动速度和热更新速度都有明显提升。

配置 Turbopack

在 next.config.ts 中，Turbopack 配置从 experimental.turbopack 提升到了顶层 turbopack：

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    // 配置选项
  },
}

export default nextConfig

常用配置项

选项	说明
root	设置应用根目录，绝对路径
rules	自定义 Webpack Loader 规则
resolveAlias	模块别名映射
resolveExtensions	自定义解析的文件扩展名
debugIds	在打包产物中生成 debug ID

自定义 Loader

Turbopack 内置了 CSS、Sass、现代 JavaScript 的编译能力，不需要额外配置 css-loader、babel-loader 这些。但如果你的项目需要特殊处理，比如把 SVG 当作 React 组件导入，就需要自定义 Loader。

基本用法

以 @svgr/webpack 为例，让 .svg 文件可以作为 React 组件使用：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

export default nextConfig

如果 Loader 需要传参数，用对象格式：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: [
          {
            loader: '@svgr/webpack',
            options: {
              icon: true,
            },
          },
        ],
        as: '*.js',
      },
    },
  },
}

export default nextConfig

高级条件匹配

Turbopack 支持精确控制 Loader 在什么场景下运行：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*': {
        condition: {
          all: [
            { not: 'foreign' }, // 排除 node_modules
            { path: /\.svg$/ },
          ],
        },
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

export default nextConfig

内置的条件运算符：

• browser：匹配客户端代码
• foreign：匹配 node_modules 中的代码
• development：仅在 next dev 时生效
• production：仅在 next build 时生效
• node：匹配 Node.js 运行时代码
• edge-light：匹配 Edge 运行时代码

模块类型

可以直接指定文件的模块类型，不需要 Loader：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        type: 'asset', // 导入时返回 URL
      },
    },
  },
}

export default nextConfig

可用的模块类型：asset、ecmascript、typescript、css、css-module、wasm、raw、bytes。

内联 Loader 配置（Next.js 16 新功能）

Next.js 16.2 引入了 turbopackLoader 导入属性，可以在单个 import 语句上应用 Loader：

import rawText from '../data.txt' with { turbopackLoader: 'raw-loader', turbopackAs: '*.js' }

export default function Page() {
  return <p>{rawText}</p>
}

这种方式不需要全局配置，只影响当前导入。

模块别名与扩展名

别名映射

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    resolveAlias: {
      underscore: 'lodash', // import from 'underscore' 实际加载 lodash
      fs: {
        browser: './empty.ts', // 浏览器环境下用空模块替代 fs
      },
    },
  },
}

export default nextConfig

自定义扩展名

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    resolveExtensions: ['.mdx', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.json'],
  },
}

export default nextConfig

注意：自定义扩展名会覆盖默认列表，记得把默认的扩展名也加上。

与 Webpack 的差异

Turbopack 不兼容所有 Webpack 特性，了解这些差异能帮你避免踩坑：

1. Loader API 部分支持：只实现了 Webpack Loader API 的核心子集。不支持 importModule、loadModule、emitFile 等。
2. 只支持返回 JavaScript 的 Loader：样式和图片转换的 Loader 目前不支持。
3. Loader 参数必须是纯 JavaScript 对象：不能传 require() 的模块作为参数。

调试 IDs

开启 debugIds 后，Turbopack 会在打包产物中注入唯一标识符，方便错误追踪系统（如 Sentry）做 source map 映射：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    debugIds: true,
  },
}

export default nextConfig

实战建议

1. 新项目直接用 Turbopack：不需要 Webpack 配置，开箱即用。
2. 旧项目迁移：先运行 Codemod 自动转换，再手动检查不兼容的 Loader。
3. 保留 Webpack 作为备选：如果遇到无法解决的问题，可以用 next build --webpack 回退。

{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack"
  }
}

Turbopack 已经是默认选项，趁早熟悉它，后面会越来越顺手。