---
title: "Turborepoとは：2.11系のturbo.json設定・キャッシュ共有・CI高速化を実装で解説"
url: "https://www.issoh.co.jp/tech/details/17773/"
published: 2026-09-24
updated: 2026-10-19
categories: ["開発"]
publisher: "株式会社一創"
---

# Turborepoとは：2.11系のturbo.json設定・キャッシュ共有・CI高速化を実装で解説

Turborepoは、Vercelが開発しているJavaScript・TypeScriptのモノレポ向けビルドシステムです。2026年9月24日時点のnpm最新版は2.11.3で、2.11では実験的ながらRust・Python・Goのワークスペースも扱えるようになりました。この記事では、create-turboによる雛形の作成、turbo.jsonのtasks定義、–filterと–affectedで変更分だけを走らせる方法、Remote Cacheの共有と署名、GitHub ActionsとDockerでの組み込み方を設定例つきで整理します。最後に、Turborepoを入れてよいリポジトリの条件と、Nxや素のワークスペースで足りる場面も言い切ります。

## まとめ：Turborepo導入前に決めるタスク定義とキャッシュ共有の範囲

Turborepoが速くするのは、パッケージマネージャのインストールではなく、build・test・lintといったタスクの実行です。入力が変わっていないタスクは実行せず、前回の出力とログを復元します。効果の大きさは、turbo.jsonのoutputsとenvをどれだけ正確に書けるかで決まります。

導入の順番は3段です。まずturbo.jsonにtasksを定義してローカルキャッシュを効かせる。次にCIで–affectedを使い、変更の影響を受けたパッケージだけを走らせる。Remote Cacheでチームとキャッシュを共有するのは最後で、ここで署名とログの扱いを決めます。

2.0で設定キーがpipelineからtasksに変わっています。検索で見つかる日本語の手順にはpipelineのままのものが残っているので、書き写す前にキー名を確認してください。

## Turborepoの定義と2.11系で広がった対応範囲、Turbopackとの違い

名前が似た製品が同じVercelにあるため、まず対象を固定します。

### Vercel製のモノレポ用ビルドシステムと2.11.3時点の版の位置

Turborepoはタスクランナー兼キャッシュ層です。ソースは[GitHubのvercel/turborepoリポジトリ](https://github.com/vercel/turborepo)で公開され、npmパッケージ名は`turbo`。npm registryの記録では、2.11.0が2026年9月18日、2.11.3が9月22日に公開されました。直近のマイナー版は2.9が2026年3月、2.10が6月、2.11が9月と、約3か月間隔で出ています。

各パッケージのpackage.jsonにあるscriptsを、依存関係の順序に沿って並列に実行する。これが基本動作です。何を実行するかはscriptsのまま、実行順とキャッシュの規則だけをturbo.jsonに書きます。

### 2.11のRust・Python・Go対応とproduction pruneの追加内容

[Turborepo 2.11の公式リリースノート](https://turborepo.dev/blog/2-11)によると、Cargoワークスペース、uvワークスペース、go.workを実験的に認識します。turbo.jsonの`futureFlags`で`experimentalCargoWorkspaces`や`experimentalPythonWorkspaces`を有効にする方式で、JavaScriptのパッケージからRustのビルドに`dependsOn`を張る書き方も示されました。

同じ版で、最初のタスクが始まるまでの時間が2.9比で最大4倍短くなり、1,037パッケージのリポジトリで45%改善したと公表されています。package.jsonの`devEngines.packageManager`の読み取りと、`turbo prune --production`も追加されました。多言語対応は実験扱いなので、本番のCIでは当面JavaScript・TypeScriptのタスクに絞るのが無難です。

### TurbopackやHotwireのTurboと取り違えないための切り分け

Turbopackは、Next.jsに組み込まれたバンドラです。1つのアプリ内でモジュールをまとめる層を担い、Turborepoは複数パッケージのタスクを束ねる層を担います。両者は併用でき、Next.jsアプリをTurborepoで管理しつつ、そのビルドの中でTurbopackが動く構成は普通です。Turbopack側の設定は[TurbopackとNext.js 16での設定と移行判断](https://www.issoh.co.jp/tech/details/16015/)で扱っています。

RailsのHotwireにある「Turbo」は、ページ遷移を速くする別のライブラリです。文書では「Turborepo」と正式名で書き、CLIだけ`turbo`と書き分けてください。

## create-turboとturbo.jsonで雛形を作り、タスクを定義する手順

新規と既存で入り口が違います。新規なら雛形から、既存なら`turbo`を足すだけです。

### create-turboでの新規作成と既存リポジトリへのturbo追加コマンド

新規は`npx create-turbo@latest`で、apps配下にアプリ、packages配下に共有パッケージを置いた構成が生成されます。既存のワークスペースに足す場合は、[公式のインストール手順](https://turborepo.dev/docs/getting-started/installation)どおりリポジトリのdevDependenciesに入れます。

```
# npm workspaces の場合
npm install turbo --save-dev

# pnpm の場合（ルートへの追加を明示）
pnpm add turbo --save-dev --ignore-workspace-root-check

# 動作確認：実行計画だけを JSON で出す
npx turbo run build --dry=json
```

グローバルインストールもできますが、版をリポジトリ側に固定しておくとCIとローカルの差が出ません。2.11時点で公式に対応するパッケージマネージャはnpm・pnpm・yarn・bunに、nubとaubeを加えた6種です。pnpmを選ぶ場合の前提は[pnpmの共有ストアとモノレポ運用](https://www.issoh.co.jp/tech/details/17573/)、版の固定は[corepackによるpnpmのバージョン管理](/tech/details/2765/)を参照してください。

### turbo.jsonのtasks・dependsOn・outputsを書く最小構成の例

最初に書くのはbuild・test・lint・devの4タスクで足ります。[turbo.jsonの設定リファレンス](https://turborepo.dev/docs/reference/configuration)に沿った最小構成を示します。

```
{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}
```

`^build`の`^`は「依存先パッケージのbuildを先に終わらせる」という意味で、packages配下のUIライブラリをapps配下より先にビルドさせます。outputsを書き忘れたタスクは、ログだけが復元されて成果物は復元されません。キャッシュヒットと表示されたのにdistが空、という症状の原因はほぼここです。

### envModeのstrict既定で変数が消える失敗とenv・globalEnvの区別

turbo.jsonの`envMode`は既定がstrictで、`env`や`globalEnv`に書いていない環境変数はタスクから見えません。ローカルでは動くのにCIだけAPIのURLが空になる、というトラブルの多くはこの既定値から来ています。

書き分けは単純です。特定のタスクのハッシュに効かせたい変数は各タスクの`env`へ。全タスクに効かせたい変数は`globalEnv`へ。値をハッシュに含めずに渡すだけでよい変数、たとえばCIのトークン類は`passThroughEnv`へ。envに書いた変数は値が変わるとキャッシュミスになるので、ビルド結果を実際に変える変数だけに絞ってください。

## turbo runの–filterと–affectedによる変更分のビルド設定

モノレポのCIが遅くなる原因は、変更していないパッケージまで毎回テストすることです。turbo runで対象を絞り、変更したパッケージやその影響範囲をビルドするために、–filterと–affectedの指定方法を分けて確認します。

### –filterのパッケージ名・ディレクトリ・Gitコミット指定を組み合わせる書き方

[turbo runのリファレンス](https://turborepo.dev/docs/reference/run)では、`--filter`に次の書き方が並んでいます。

- `--filter=ui`：パッケージ名で指定
- `--filter=./apps/*`：ディレクトリで指定
- `--filter=[HEAD^1]`：直前のコミットから変わったパッケージ
- `--filter=@acme/ui...[HEAD^1]`：依存関係の展開と変更検知の組み合わせ

実務で最初に覚えるのは、パッケージ名の後ろに付ける`...`です。`--filter=ui...`はuiとuiに依存するパッケージをすべて含み、共有コンポーネントを直したときに影響するアプリだけを確かめられます。

### –affectedとTURBO\_SCM\_BASEでのプルリクエスト差分の検証設定

`--affected`は`--filter=...[main...HEAD]`と同じ意味で、mainとの差分に影響を受けるパッケージとその依存元を対象にします。基準のブランチがmainでない場合は、環境変数`TURBO_SCM_BASE`と`TURBO_SCM_HEAD`で上書きします。

```
# develop ブランチを基準にしている場合
TURBO_SCM_BASE=origin/develop npx turbo run lint test --affected

# 実行されるタスクとハッシュを事前に確認
npx turbo run test --affected --dry=json
```

差分の計算にはmain側のコミットが必要です。CIでチェックアウトを浅くしすぎると比較ができず、意図より広い範囲が走ります。GitHub Actions側でパス単位の起動制御を組みたい場合は、[GitHub Actionsのトリガーとpathsフィルタの設計](https://www.issoh.co.jp/tech/details/16923/)と役割を分け、ワークフローの起動はpaths、パッケージの選別はTurborepoに任せると重複しません。

### –graphと–summarizeで依存グラフと実行結果を記録する運用

`--graph`はタスクの依存グラフをsvg・html・mermaid・dotで出力します。`--summarize`は`.turbo/runs`にJSONを書き出し、どのタスクがキャッシュから復元され、どれが実行されたかをハッシュつきで残します。

キャッシュが効かない原因は、2回分のsummaryを並べてハッシュの入力を比べれば特定できます。

## ローカルキャッシュとVercel Remote Cacheをチームで共有する設定と署名

ローカルキャッシュは各自の`.turbo`配下に溜まります。これをCIと開発者全員で共有するのがRemote Cacheです。

### Vercel Remote Cacheの料金と認証・チームへの接続手順

Vercel Remote Cacheは2024年12月に無料化され、[Remote Cachingの公式ドキュメント](https://turborepo.dev/docs/core-concepts/remote-caching)でも全プランで無料、Vercelでホスティングしていなくても使えると明記されています。ローカルでは`npx turbo login`で認証し、`npx turbo link`でリポジトリをチームに紐づけます。

読み書きの権限は`--cache`で分けられ、既定は`local:rw,remote:rw`です。開発者の端末は`remote:r`で読むだけにし、書き込みはCIに限る。この分け方にすると、手元の未コミットの状態から作られた成果物がチームに配られる事故を防げます。

### remoteCache.signatureと秘密鍵によるキャッシュ改ざんの検知設定

turbo.jsonに`"remoteCache": { "signature": true }`を書き、環境変数`TURBO_REMOTE_CACHE_SIGNATURE_KEY`に秘密鍵を置くと、アップロード時にHMAC-SHA256で署名されます。ダウンロード時の検証に失敗した成果物はキャッシュミスとして扱われ、使われません。

キャッシュは他人が作った成果物をそのまま実行環境へ持ち込む仕組みです。トークンが漏れれば、書き換えた成果物をCIに配れてしまいます。Remote Cacheを有効にするなら、署名は同時に入れるものと決めてください。

### ログもキャッシュされる仕様とセルフホストのRemote Cacheを選ぶ条件

Turborepoはタスクのログも成果物として保存します。テストの途中でトークンや接続文字列を標準出力に出していると、それがキャッシュに残り、チーム全員の端末で再生されます。Remote Cacheを入れる前に、ログへ秘密を出していないかをgrepで確かめてください。

成果物を社外に置けない場合は、公開されているOpenAPI仕様に沿ったHTTPサーバーを自前で立て、`turbo login --manual`で接続できます。ただし保存先の容量と権限管理を自分で持つことになるため、取引先との契約でソースや成果物の外部保存が禁じられている場合に限って選ぶのが妥当です。

## GitHub ActionsとDockerでのTurborepo実行とCI構成

ここまでのTurborepoの設定をGitHub ActionsのCIに載せ、Dockerではturbo pruneでアプリ単位のビルドに必要なファイルを絞り込みます。使う環境変数は`TURBO_TOKEN`と`TURBO_TEAM`の2つです。

### TURBO\_TOKENとTURBO\_TEAMを渡すCIワークフローの設定例

[公式のGitHub Actionsガイド](https://turborepo.dev/docs/guides/ci-vendors/github-actions)は、トークンをsecrets、チーム名をvarsから渡す形を示しています。これに–affectedを組み合わせたnpm workspaces向けの例です。

```
name: CI
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx turbo run lint test build --affected
```

`fetch-depth: 0`はmainとの差分を取るための指定で、公式例の`fetch-depth: 2`は直前コミットとの比較を前提にしています。Remote Cacheを使わない場合は、`.turbo`ディレクトリを`actions/cache`で保存する方法も公式に案内されています。キーの設計は[actions/cacheのkey設計と復元されない原因の切り分け](https://www.issoh.co.jp/tech/details/16933/)が詳しく、パッケージのインストールキャッシュとturboのタスクキャッシュは別のキーで持つのが基本です。

### turbo prune –dockerによるアプリ単位のイメージ構築例

[turbo pruneのリファレンス](https://turborepo.dev/docs/reference/prune)によると、`turbo prune web --docker`は`out/json`に必要なパッケージのpackage.jsonだけ、`out/full`にソース一式、`out`直下に絞り込んだロックファイルを出力します。以下のDockerfileは、アプリ単位のDockerイメージを作る構成例です。依存のインストール層とソースのコピー層を分けられるので、ソースだけを直したときにnpm ciの層が再利用されます。

```
FROM node:20-alpine AS base
WORKDIR /app

FROM base AS prepare
RUN npm install -g turbo@^2
COPY . .
RUN turbo prune web --docker

FROM base AS builder
COPY --from=prepare /app/out/json/ .
COPY --from=prepare /app/out/package-lock.json ./package-lock.json
RUN npm ci
COPY --from=prepare /app/out/full/ .
RUN npx turbo run build --filter=web
```

2.11の`--production`を付けると、devDependenciesからしか参照されないワークスペースパッケージが除外されます。既定はfalseなので、テスト用の内部パッケージを本番イメージに含めたくない場合に明示してください。Dockerのビルドキャッシュ全般の設計は[GitHub ActionsでのDockerイメージビルドとキャッシュ設計](https://www.issoh.co.jp/tech/details/16943/)にまとめています。

### Docker内でRemote Cacheを使うときにトークンをイメージへ残さない渡し方

[公式のDockerガイド](https://turborepo.dev/docs/guides/tools/docker)の例は、`TURBO_TOKEN`をARGとENVでビルドステージへ渡しています。この書き方はENVの値がそのステージのイメージに残るため、builderステージをそのままpushする構成では漏えいの経路になります。

pushするのはrunnerステージだけに限るか、BuildKitの`--mount=type=secret`でRUNの実行中だけ読ませる形に変えてください。

## Turborepoを採用してよいリポジトリ条件と、Nxや素のワークスペースで足りる場面

ここは判断を言い切ります。Turborepoは「入れれば速くなる」道具ではありません。

### Turborepoを採用してよいのはパッケージ5つ以上かつCIが10分を超える構成

採用を勧めるのは、ワークスペースのパッケージがおおむね5つ以上あり、プルリクエストごとのCIが10分を超えている場合です。この規模になると、変更していないパッケージのテストが待ち時間の大半を占め、–affectedとキャッシュの効果が数字で見えます。

もう1つの条件は、ビルド成果物のディレクトリが揃っていることです。distや.nextのように出力先が決まっていれば、outputsを書くだけで済みます。パッケージごとに出力先がばらばらなら、先にビルド設定を揃えるほうが先決です。

### アプリ1つとライブラリ1つの構成ではワークスペースだけで足りる理由

アプリ1つと共有ライブラリ1つ程度なら、npmやpnpmのワークスペース機能だけで十分です。`pnpm -r run build`のような再帰実行で順序も守られ、キャッシュがなくても全体のビルドは数分で終わります。

この規模でTurborepoを入れると、turbo.jsonとoutputsとenvの保守が増えるだけで、短縮できる時間はわずかです。envの書き漏れでCIが落ちる新しい失敗の型も抱えます。モノレポにするかどうかの判断自体は[モノレポとマルチリポジトリの違いとツールの選び方](https://www.issoh.co.jp/tech/details/3934/)で先に固めてください。

### Nxを選ぶべき場面とTurborepoからの切り替えを検討する境界

Nxは、タスク実行に加えてコード生成やプラグインによる各フレームワーク連携まで持つ、より広い範囲の道具です。Angularを含むプロジェクトをフレームワーク別のプラグインで一括管理したい、という要件があるならNxのほうが合います。比較の詳細は[Nx monorepoの機能比較と運用の落とし穴](https://www.issoh.co.jp/tech/details/12650/)で扱っています。

逆に、既存のpackage.jsonのscriptsを変えずに速くしたいだけならTurborepoが軽い選択です。Turborepoにもジェネレーター機能はあり、[turbo/genによるパッケージ雛形の生成](https://www.issoh.co.jp/tech/details/12463/)で足りる範囲なら、Nxへ移る理由にはなりません。

### モノレポのCI改善を社内だけで進めにくいときの外部相談の目安

turbo.jsonの設計、Remote Cacheの署名、Dockerイメージの分割は、どれもCI全体の構成と一緒に見直す作業です。パイプラインの前提を整理するなら[CI/CDの仕組みとパイプライン構成の判断基準](https://www.issoh.co.jp/column/details/13002/)が起点になります。

既存システムの保守と並行してCIを組み替える余力が社内にない場合は、[保守運用・内製化支援](https://www.issoh.co.jp/service/system/maintenance/)のように、運用を引き受けながら社内へ手順を移していく体制を検討する余地があります。切り戻しの手順を用意したうえでジョブ単位で置き換える進め方なら、本番リリースを止めずに移行できます。

## よくある質問

Turborepoの導入検討でよく挙がる質問に、2.11系の仕様を前提に答えます。

### Turborepoは無料で使えますか？

無料です。本体はGitHubで公開されたオープンソースで、npmパッケージ`turbo`として導入します。Vercel Remote Cacheも2024年12月に無料化され、全プランで使え、Vercelでのホスティングも不要。成果物を社外に置けない場合はセルフホストという道もあります。

### turbo.jsonのpipelineとtasksはどちらを使えばよいですか？

2.0以降はtasksです。1.x系のトップレベルのpipelineキーは2.0でtasksに置き換わりました。古い手順を参考にしている場合は、公式の`npx @turbo/codemod migrate`で設定を移行できます。2022年前後に書かれた解説はpipelineのままのことが多いため、書き写す前にキー名と`$schema`のURLを確認してください。

### キャッシュヒットしたのにビルド成果物が復元されないのはなぜですか？

ほとんどの場合、そのタスクのoutputsに成果物のディレクトリが書かれていません。outputsが空だとログだけが保存されます。`--summarize`のJSONで、キャッシュに含まれたファイルを確認してください。

### TurborepoとTurbopackは同じものですか？

別の製品です。どちらもVercel製ですが、Turbopackはアプリ内のモジュールをまとめるバンドラ、Turborepoは複数パッケージのタスクを依存順に実行してキャッシュするビルドシステムです。併用でき、競合しません。

### pnpm以外のパッケージマネージャでもTurborepoは動きますか？

動きます。2.11時点の公式ドキュメントでは、npm・pnpm・yarn・bunに加えてnubとaubeが対応として挙がっています。2.11ではpackage.jsonの`devEngines.packageManager`の読み取りにも対応しました。選択は、ロックファイルの扱いやワークスペースの機能で決めてかまいません。Turborepo側の設定はどれを選んでもほぼ同じです。

## 関連記事

- [モノレポ（Monorepo）とは？マルチリポジトリとの違い・メリットとツールの選び方](https://www.issoh.co.jp/tech/details/3934/)：Turborepoを入れる前提となるリポジトリ構成の判断を整理できます
- [Nx monorepoとは｜2026年の機能・比較・導入手順と運用の落とし穴](https://www.issoh.co.jp/tech/details/12650/)：Turborepoとの比較対象になるNxの機能範囲を確認できます
- [turbo/genの基本機能とTurborepoモノレポ開発で果たす役割の全体像](https://www.issoh.co.jp/tech/details/12463/)：Turborepoのジェネレーター機能で新規パッケージを作る手順を補えます
- [pnpmとは？共有ストアの仕組みとv12のRust実装・モノレポ運用を解説](https://www.issoh.co.jp/tech/details/17573/)：Turborepoと組み合わせるパッケージマネージャ側の前提を確認できます
- [GitHub Actionsのキャッシュ｜actions/cacheのkey設計と復元されない原因の切り分け](https://www.issoh.co.jp/tech/details/16933/)：Remote Cacheを使わずに.turboを保存する場合のキー設計に使えます

---

出典: [Turborepoとは：2.11系のturbo.json設定・キャッシュ共有・CI高速化を実装で解説](<https://www.issoh.co.jp/tech/details/17773/>)（株式会社一創）