# 依存関係のキャッシュ (Fast Cache)

> Latchkey Fast Cache は、依存関係のキャッシュを単一のストリーミングリクエストで保存および復元します。ストレージはランナーと同じリージョンに置かれ、設定は不要です。

Source: https://latchkey.dev/ja/documentation/dependency-caching

## Summary

- `actions/cache` を `latchkey-dev/cache-action@v1` に置き換えるだけです。既存の `path`、`key`、`restore-keys` の入力はそのまま引き継がれます。
- 保存または復元ごとに 1 回のストリーミングリクエスト、マルチスレッドの zstd 圧縮、ランナーのリージョン内のストレージ。
- 設定不要: ストレージと認証情報はすべての Latchkey ランナーにあらかじめプロビジョニングされています。
- キャッシュの問題はビルドを遅くすることはあっても、失敗させることは決してありません。復元の失敗は警告を出して続行します。

Latchkey Fast Cache (`latchkey-dev/cache-action@v1`) は、Latchkey のマネージドランナー上で依存関係のキャッシュ (node_modules、パッケージレジストリ、ビルド成果物) を保存および復元する軽量な GitHub Action です。繰り返しの実行では、パイプラインですでに完了したインストールをスキップします。

## なぜ速いのか

- キャッシュデータは、`actions/cache@v4` が使うシリアルなチャンク方式ではなく、**単一のストリーミング HTTP リクエスト**で転送されます。チャンクごとのラウンドトリップも一時ファイルもありません。
- 圧縮と展開は**マルチスレッド (zstd)** で行われ、アップロードとダウンロードは並列転送として実行されます。
- ストレージは**ランナーと同じリージョン**に置かれるため、バイトが遠くまで移動することはありません。
- 各保存と復元はジョブログにその所要時間を出力するので、自分のビルドで差を測定できます。

## キャッシュにどれだけの価値があるか: 実例

以下の数字は実測のベンチマークではなく説明用の例です: 得られる効果の形を示すものであり、あなた自身のビルドでは異なる結果になります。`latchkey-medium` 上で ~400 MB の `node_modules` を持つ Node.js アプリを想像してください。キャッシュなしでは、`npm ci` は実行のたびにすべてを解決してダウンロードします: 仮に約 3 分 (180 秒) としましょう。キャッシュヒットの場合、復元はオンザフライで展開される単一のストリーミングダウンロードで、数秒 (たとえば ~10 秒) で完了します。さらにヒット時にインストールステップをスキップすれば (下のワークフロー例はまさにそうしています)、3 分のインストールは丸ごと消えます。それでも `npm ci` を実行するチームでも、ウォームな `node_modules` に対しては数十秒で完了します。ヒット時のパスは 180 秒ではなく約 30 秒の依存関係処理と見積もれます。

この前提では、おおよそ**実行あたり 2.5 分の節約**となり、週 100 回の実行なら**週あたり約 250 ランナー分**、4 時間強に相当します。キャッシュがすべての実行に効くわけではありません: ロックファイル変更後のコールドなキーは、フルインストールに加えて保存の分 (ここでは ~195 秒) を支払うことになり、キャッシュがまったくない場合よりわずかに悪くなります。見返りは、その後に続くすべてのヒットです。

> **自分のビルドで測定する**
> あなたの数字は、依存関係のサイズ、ロックファイルの変更頻度、ネットワーク状況に依存します。正直な調べ方は、同じワークフローを 2 回実行し、GitHub が表示するステップの所要時間を比較することです。1 回目はミスと保存、2 回目はヒットです。`Cache restored in {N}ms` と `Cache saved in {N}ms` のログ行が、キャッシュ側の内訳を直接教えてくれます。

## ワークフローに追加する

2 つのステップを追加します。1 つは `action: restore`、もう 1 つは `action: save` です。それぞれ `key` と 1 つ以上の `path` エントリ (改行またはスペース区切り。`~` に対応) を受け取ります。restore ステップは `cache-hit` の出力を公開するので、キャッシュがヒットしたときにインストールステップをスキップできます。

```.github/workflows/ci.yml
jobs:
  build:
    runs-on: latchkey-medium
    steps:
      - uses: actions/checkout@v4

      - name: Restore dependencies
        id: cache
        uses: latchkey-dev/cache-action@v1
        with:
          action: restore
          key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
          path: node_modules

      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: npm ci

      - name: Save dependencies
        uses: latchkey-dev/cache-action@v1
        with:
          action: save
          key: deps-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
          path: node_modules
```

## actions/cache からの移行

> **Latchkey ランナー限定**
> Fast Cache は Latchkey のマネージドランナー (`latchkey-small` から `latchkey-xlarge` およびカスタムラベル) 上で動作します。他のランナーではこの action は動作しないため、そこでは `actions/cache@v4` を使い続けてください。

## 安全なデフォルト

- **復元の失敗がジョブを失敗させることは決してありません**: 警告が表示され、`cache-hit` は `false` となり、実行は続行します。
- **key がすでに存在する場合、保存は自動的にスキップされます**。そのため、同一のキャッシュが再アップロードされることはありません。
- キャッシュは**組織ごとに分離**され、オペレーティングシステムごとに自動的にバージョン管理されます。より細かい分離 (OS バージョンなど) はキャッシュキーにエンコードしてください。
- キャッシュエントリはサーバー側に **14 日間の保持期間** で保存されるため、古くなったキャッシュは自然に消えていきます。

## ジョブログに表示される内容

| ログ行 | 意味 |
| --- | --- |
| `Cache restored in {N}ms` | 復元が完了したこと、およびその所要時間 |
| `Cache saved in {N}ms` | 保存が完了したこと、およびその所要時間 |
| `Cache miss` | その key のキャッシュが存在しなかったこと。`cache-hit` は `false` となり、ジョブは続行します |
| `Cache already exists for key=..., skipping save` | 同一の key がすでに保存されているため、保存がスキップされたこと |

## 探さなくてよいキャッシュ

[AI Scan](/documentation/custom-runners) はプロジェクトに必要なキャッシュを検出し、提案されるランナー設定に一覧表示します。[AI Insight](/documentation/optimization-insights) の "Get more from Latchkey" セクションは、ワークフローへの Latchkey キャッシュの追加をワンクリックの "Add Latchkey caching" PR として提案でき、Migrate Runners ツールはワークフローを移行する際にキャッシュステップを注入できます。キャッシュを手作業で調整しないチームでも、キャッシュの恩恵を受けられます。

より広い技術 (インストール時間の短縮、遅いスイートの分割、並列化) については、Learn ライブラリに、任意のランナーで適用できるガイドを備えた実践的な [CI 最適化ハブ](/learn/optimize-ci) があります。

### actions/cache から Fast Cache へはどう切り替えますか?

`actions/cache` を `latchkey-dev/cache-action@v1` に置き換えてください。既存の `path`、`key`、`restore-keys` の入力はそのまま使えるため、差分は 1 行で、これまで想定してきたキャッシュの挙動も変わりません。

### Fast Cache が actions/cache より速い理由は?

保存・復元ごとに複数ステップのアップロードではなく 1 回のストリーミングリクエストで済むこと、マルチスレッドの zstd 圧縮、そしてランナーと同一リージョンのストレージです。短縮されるのは転送と展開で、キャッシュ処理の所要時間の大半を占める部分です。

### キャッシュが失敗したらどうなりますか?

ビルドは続行します。復元に失敗した場合はログに警告を出し、そのまま通常のインストールに進むため、キャッシュの問題でビルドが遅くなることはあっても失敗することはありません。これは意図的な設計です。キャッシュは最適化であり、パイプラインを壊しうる最適化は負債だからです。

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt