Turbopack 配置 #

turbo.json 配置文件 #

基本结构 #

json

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    }
  }
}

配置项详解 #

配置项	类型	描述
`$schema`	string	JSON Schema 地址
`globalDependencies`	string[]	全局依赖文件
`globalEnv`	string[]	全局环境变量
`globalPassThroughEnv`	string[]	透传环境变量
`pipeline`	object	任务管道配置
`ui`	string	UI 模式

Pipeline 配置 #

任务依赖 #

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

dependsOn 语法：

语法	含义
`^build`	依赖所有包的 build 任务
`build`	依赖当前包的 build 任务
`//#build`	依赖根目录的 build 任务

多任务配置 #

json

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "outputMode": "new-only"
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*"]
    },
    "lint": {
      "outputs": [],
      "inputs": ["src/**/*", ".eslintrc.json"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "clean": {
      "cache": false
    }
  }
}

任务选项 #

json

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "outputMode": "new-only",
      "inputs": ["src/**/*"],
      "outputFileOutputs": ["dist/**/*.js"],
      "env": ["API_URL", "NODE_ENV"],
      "dependsOn": ["^build"]
    }
  }
}

outputMode 选项：

值	描述
`full`	显示完整输出
`new-only`	只显示新输出
`hash-only`	只显示哈希
`none`	不显示输出

Next.js 集成配置 #

基本配置 #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      resolveExtensions: ['.tsx', '.ts', '.jsx', '.js'],
      resolveAlias: {
        '@': './src',
      },
    },
  },
}

完整配置示例 #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      resolveExtensions: [
        '.tsx',
        '.ts',
        '.jsx',
        '.js',
        '.json',
        '.css',
        '.scss',
      ],
      resolveAlias: {
        '@': './src',
        '@components': './src/components',
        '@lib': './src/lib',
        '@hooks': './src/hooks',
        '@utils': './src/utils',
        '@styles': './src/styles',
        '@types': './src/types',
        '@assets': './src/assets',
      },
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
  reactStrictMode: true,
  swcMinify: true,
}

resolveExtensions 配置 #

javascript

module.exports = {
  experimental: {
    turbo: {
      resolveExtensions: [
        '.tsx',    // TypeScript JSX
        '.ts',     // TypeScript
        '.jsx',    // JavaScript JSX
        '.js',     // JavaScript
        '.json',   // JSON
        '.css',    // CSS
        '.scss',   // SCSS
        '.less',   // Less
      ],
    },
  },
}

resolveAlias 配置 #

javascript

module.exports = {
  experimental: {
    turbo: {
      resolveAlias: {
        '@': './src',
        '@/components': './src/components',
        '@/lib': './src/lib',
        '@/hooks': './src/hooks',
        '@/utils': './src/utils',
        '@/styles': './src/styles',
        '@/types': './src/types',
        '@/assets': './src/assets',
        '@/config': './src/config',
        '@/services': './src/services',
        '@/store': './src/store',
      },
    },
  },
}

模块解析配置 #

路径映射 #

typescript

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "@lib/*": ["./src/lib/*"],
      "@hooks/*": ["./src/hooks/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      resolveAlias: {
        '@': './src',
        '@components': './src/components',
        '@lib': './src/lib',
        '@hooks': './src/hooks',
        '@utils': './src/utils',
      },
    },
  },
}

外部模块 #

javascript

module.exports = {
  experimental: {
    turbo: {
      external: [
        'react',
        'react-dom',
        'lodash',
        'moment',
      ],
    },
  },
}

条件导出 #

json

// package.json
{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "require": "./dist/utils.cjs"
    }
  }
}

缓存配置 #

缓存目录 #

json

// turbo.json
{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

缓存策略 #

json

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["src/**/*", "package.json"],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*", "test/**/*"],
      "cache": true
    }
  }
}

远程缓存 #

bash

# 启用远程缓存
turbo login
turbo link

# 配置远程缓存
turbo config set team my-team

json

// turbo.json
{
  "remoteCache": {
    "enabled": true,
    "signature": true
  }
}

缓存忽略 #

json

{
  "pipeline": {
    "build": {
      "outputs": [
        ".next/**",
        "!.next/cache/**",
        "!.next/trace"
      ]
    }
  }
}

环境变量配置 #

全局环境变量 #

json

// turbo.json
{
  "globalEnv": [
    "NODE_ENV",
    "API_URL",
    "DATABASE_URL"
  ]
}

任务环境变量 #

json

{
  "pipeline": {
    "build": {
      "env": [
        "NEXT_PUBLIC_API_URL",
        "NEXT_PUBLIC_ANALYTICS_ID"
      ]
    },
    "test": {
      "env": [
        "TEST_DATABASE_URL",
        "TEST_API_KEY"
      ]
    }
  }
}

透传环境变量 #

json

{
  "globalPassThroughEnv": [
    "CI",
    "GITHUB_TOKEN",
    "VERCEL_URL"
  ]
}

.env 文件 #

bash

# .env.local
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key
NEXT_PUBLIC_API_URL=https://api.example.com

# .env.development
NODE_ENV=development
DEBUG=true

# .env.production
NODE_ENV=production
DEBUG=false

输入输出配置 #

输入配置 #

json

{
  "pipeline": {
    "build": {
      "inputs": [
        "src/**/*",
        "public/**/*",
        "package.json",
        "next.config.js",
        "tsconfig.json"
      ]
    },
    "test": {
      "inputs": [
        "src/**/*.ts",
        "src/**/*.tsx",
        "test/**/*.ts",
        "jest.config.js"
      ]
    }
  }
}

输出配置 #

json

{
  "pipeline": {
    "build": {
      "outputs": [
        ".next/**",
        "!.next/cache/**",
        "public/dist/**"
      ]
    },
    "test": {
      "outputs": [
        "coverage/**",
        "test-results/**"
      ]
    }
  }
}

Monorepo 配置 #

工作区配置 #

json

// package.json (root)
{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

Monorepo turbo.json #

json

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "clean": {
      "cache": false
    }
  }
}

包级别配置 #

json

// packages/ui/turbo.json
{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

依赖图 #

text

┌─────────────────────────────────────────────────────────────┐
│                    Monorepo 依赖图                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   app-web ──► @acme/ui ──► @acme/utils                      │
│       │           │              │                          │
│       │           └──────────────┘                          │
│       │                                                      │
│       └──► @acme/api ──► @acme/database                     │
│                                                              │
│   app-admin ──► @acme/ui ──► @acme/utils                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

自定义规则配置 #

Loader 配置 #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
        '*.md': {
          loaders: ['raw-loader'],
          as: '*.js',
        },
        '*.yaml': {
          loaders: ['yaml-loader'],
          as: '*.json',
        },
      },
    },
  },
}

SVG 组件化 #

javascript

module.exports = {
  experimental: {
    turbo: {
      rules: {
        '*.svg': {
          loaders: [
            {
              loader: '@svgr/webpack',
              options: {
                icon: true,
                replaceAttrValues: {
                  '#000': 'currentColor',
                },
              },
            },
          ],
          as: '*.js',
        },
      },
    },
  },
}

tsx

import Logo from '@/assets/logo.svg';

export function Header() {
  return (
    <header>
      <Logo className="w-10 h-10" />
    </header>
  );
}

Markdown 导入 #

javascript

module.exports = {
  experimental: {
    turbo: {
      rules: {
        '*.md': {
          loaders: ['frontmatter-markdown-loader'],
          as: '*.js',
        },
      },
    },
  },
}

tsx

import content from './about.md';

export function AboutPage() {
  return (
    <div>
      <h1>{content.attributes.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: content.html }} />
    </div>
  );
}

性能配置 #

并行配置 #

json

// turbo.json
{
  "parallel": 4
}

bash

# 命令行指定
turbo build --parallel=4

内存限制 #

bash

# 设置 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" turbo build

缓存大小 #

json

{
  "cacheOptions": {
    "maxCacheSize": 10737418240
  }
}

构建优化配置 #

代码分割 #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      chunkSplitting: {
        strategy: 'default',
        overrides: {
          vendor: {
            test: /[\\/]node_modules[\\/]/,
            name: 'vendors',
          },
        },
      },
    },
  },
}

Tree Shaking #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      treeShaking: true,
      sideEffects: false,
    },
  },
}

压缩配置 #

javascript

module.exports = {
  experimental: {
    turbo: {
      minify: true,
      minifyOptions: {
        compress: {
          drop_console: true,
          drop_debugger: true,
        },
      },
    },
  },
}

调试配置 #

日志级别 #

bash

# 详细日志
turbo build --log-level verbose

# 调试模式
turbo build --debug

# 性能分析
turbo build --profile

输出诊断 #

json

{
  "pipeline": {
    "build": {
      "outputMode": "full"
    }
  }
}

缓存诊断 #

bash

# 查看缓存信息
turbo build --dry-run

# 强制重新构建
turbo build --force

# 查看任务图
turbo build --graph

配置最佳实践 #

1. 合理设置缓存 #

json

{
  "pipeline": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"],
      "inputs": ["src/**/*", "package.json"]
    }
  }
}

2. 明确依赖关系 #

json

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "dependsOn": ["^build"]
    }
  }
}

3. 环境变量管理 #

json

{
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "env": ["NEXT_PUBLIC_*"]
    }
  }
}

4. Monorepo 配置继承 #

json

// packages/ui/turbo.json
{
  "extends": ["//"],
  "pipeline": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

配置示例 #

完整配置示例 #

javascript

// next.config.js
module.exports = {
  experimental: {
    turbo: {
      resolveExtensions: ['.tsx', '.ts', '.jsx', '.js', '.json'],
      resolveAlias: {
        '@': './src',
        '@components': './src/components',
        '@lib': './src/lib',
        '@hooks': './src/hooks',
        '@utils': './src/utils',
        '@styles': './src/styles',
        '@types': './src/types',
        '@assets': './src/assets',
      },
      rules: {
        '*.svg': {
          loaders: ['@svgr/webpack'],
          as: '*.js',
        },
      },
    },
  },
  reactStrictMode: true,
  swcMinify: true,
  images: {
    domains: ['images.example.com'],
  },
}

json

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**"],
      "outputMode": "new-only"
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": [],
      "inputs": ["src/**/*", ".eslintrc.json"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["src/**/*", "test/**/*"]
    },
    "type-check": {
      "outputs": [],
      "inputs": ["src/**/*", "tsconfig.json"]
    }
  }
}

下一步 #

现在你已经了解了 Turbopack 的配置选项，接下来学习核心特性深入了解 Turbopack 的强大功能！