# cache key vs restore key: CIのcacheルックアップの仕組み

> cache keyは保存とルックアップの正確なエントリ; restore keysはニアミスのためのprefix fallbackだ。両者がどう鮮度とhitのバランスを取るかを学ぼう。

Source: https://latchkey.dev/ja/learn/ci-cd-concepts/cache-key-vs-restore-key  
Updated: 2026-06-25

cache keyは、あなたが保存し最初に探す正確な名前だ。restore keysはニアミスを捕まえるprefixで、小さな変更が何もない代わりに有用な古いcacheを復元する。

CIのcacheには、人々が混同する2つのつまみがある: 正確なkeyと、fallbackのrestore keysだ。ルックアップが一方から他方へどう歩くかを理解することが、高いhit率と新鮮なデータの両方の鍵だ。

## 正確なkey

保存時、cacheはkeyの下に格納される。復元時、runnerはまず完全一致を探す。完全一致が理想だ: この依存関係セットのためのcacheを正確に復元する。keyは通常lockfileのhashを埋め込むため、変わるべきときだけ変わる。

## restore keys(prefixのfallback)

完全一致がなければ、runnerは各restore keyを*prefix*として試し、そのprefixで始まるkeyを持つ最新のcacheを取る。つまり変わったlockfile(新しい正確なkey、完全hitなし)でも、前の実行のstoreを復元し、インストーラにdeltaだけを更新させられる。

```Exact key + prefix fallback
key: deps-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  deps-
```

## save vs restoreのセマンティクス

- save: 正確なkeyの下に書き込む(そのkeyが既にあればno-op)。
- restore: まず正確なkey、次にrestore-keysをprefixとして、最新が勝つ。
- restore-keyのhitは部分的だ - インストーラが差分を調整する。

## トレードオフの調整

restore keysなしで具体的すぎるkey → 頻繁な完全missとcoldインストール。緩すぎるprefix → 古く肥大化したcacheを復元しうる。きつい正確なkeyに、妥当なprefixのfallbackを加えると、一致では鮮度、missではwarm startが得られる。

## FAQ

### What is Cache key vs restore Key: how CI cache lookups work?

CI caching has two knobs that people conflate: the precise key and the fallback restore keys. Understanding how a lookup walks from one to the other is the key to both high hit rates and fresh data.

### The exact key?

On save, the cache is stored under the key. On restore, the runner first looks for an exact match. A perfect match is the ideal: it restores precisely the cache for this dependency set. The key usually embeds a lockfile hash so it changes only when it should.

### Restore keys (prefix fallback)?

If there is no exact match, the runner tries each restore key as a *prefix*, taking the most recent cache whose key starts with that prefix. This means a changed lockfile (new exact key, no exact hit) can still restore the previous run’s store and let the installer update just the delta.

### Tuning the trade-off?

Too specific a key with no restore keys → frequent total misses and cold installs. Too loose a prefix → you may restore a stale, bloated cache. A tight exact key plus a sensible prefix fallback gives you freshness on a match and a warm start on a miss.

---

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