V1、Berry、CI/CD向けYarnクリアキャッシュのガイド

あなたは yarn install、そしてあなたが直前に更新した依存関係はまだ古いビルドに解決する。あるいは、あなたのノートパソコンはインストールがうまくいくが、CIは無害なロックファイルの変更後突然失敗する。あるいは、Dockerのビルドは、キャッシュを使用しているにもかかわらず、長く続く。

通常はその時、人々は Yarn clear cache を検索し、最初のコマンドを貼り付ける。

時々、それが機能する。時々、それが何も解決しない。理由は単純である: Yarnのキャッシュの動作は、実行中のYarnによって大きく異なるため、キャッシュのスコープ、プロジェクトがローカルキャッシュまたは共有キャッシュを使用しているかどうか、そして実際の問題がキャッシュそのものであるかどうかが重要である。 Yarn Classic v1 と Yarn Berry v2+ の差は大きすぎる。正しいコマンドと正しいトラブルシューティング戦略を変更するのに十分である。

ほとんどのガイドはここまでで終わる。実際にはこれが始まりである。キャッシュのスコープ、プロジェクトがローカルキャッシュまたは共有キャッシュを使用しているかどうか、そして実際の問題がキャッシュそのものであるかどうかが重要である。CIとDockerでは、キャッシュ戦略が悪いと、古いパッケージアーカイブよりも多くの痛みを与えることがある。 yarn cache clean目次

ビルドが壊れたら、Yarnのキャッシュが原因かもしれない

context
Yarn キャッシュをクリアする時と理由
- キャッシュの問題を示す症状
- Yarn キャッシュをクリアする時ではない時
Yarn Classic v1 でキャッシュをクリアする方法
- 実行されるコマンドの内容
- キャッシュの保存場所を確認する方法
Yarn Berry v2+ でキャッシュを管理する方法
- Berry ではキャッシュのモデルが変わりました
- Berry での重要なコマンド
CI/CD と Docker のための Yarn キャッシュのベストプラクティス
- パイプラインでキャッシュをクリアすることはよくありません
- CI と Docker のためのより良いアプローチ
Yarn キャッシュのトラブルシューティング
- ターゲットのクリーンがまだ古いパッケージを残している場合
- キャッシュの問題と見なされるように見えるパーミッションや環境の問題
Yarn キャッシュをクリアすることについてよくある質問

あなたのビルドが壊れており、Yarn キャッシュが原因である可能性があります

よくあるパターンは次のようになります。パッケージをアップグレードし、最新の変更を取得し、再度インストールを実行します。コマンドは完了しますが、アプリは古い依存関係が存在しているように動作します。すると誰かがキャッシュをクリアすることを提案し、そしてあなたはそれは本当の解決策かただの迷信かどうかを疑うようになります。

それは本当の解決策である可能性があります。ただし、ただの妄想である可能性もあります。

キャッシュの問題は、予測可能な方法で表現されます。ローカルパッケージが更新されない。CIが予想外のものを取得する。新しいブランチがメインブランチと異なる動作をする。ロックファイルはすべて一致しているはずですが、実際には異なる動作をする。広範なパイプラインの不安定性を追跡している場合、キャッシュのデバッグをシステム的ビルドレビューと組み合わせることが役立ちます。 Capacitor CI/CD Pipelines内のビルドエラーを修正する.

実践的なルール: Yarnのキャッシュクリアを診断ツールとして扱う

Yarnのキャッシュモデルが時間の経過とともに変更されたため、古いプロジェクトではキャッシュはグローバルに共有されていたが、新しいプロジェクトではキャッシュクリーンアップはプロジェクト単位、グローバル、または両方に依存するコマンドフラグによって異なる。なぜなら、チームメンバーが「Yarnのキャッシュをクリアしてください」と言っても、最初の質問は「どのYarn?」であるから。キャッシュクリーンアップの正しい方法は、まずコンテキストを理解することである。ローカルマシンまたはCIランナー、Yarn v1またはBerry、共有キャッシュまたはプロジェクトキャッシュ。そうすることで、コマンドは具体的になり、望ましいものになる。

Yarnのキャッシュクリアの時期と理由

Yarnのキャッシュクリアは、特定のエラー状態を想定して行うことができる。最も役立つのは、古いパッケージアーティファクトを削除したり、ダウンロード状態を回復したり、または意図的に保存されたパッケージを削除してYarnがスクラッチから再構築するようにすることである。

キャッシュクリアの時期と理由のグラフィック

キャッシュクリーンアップの症状

キャッシュクリーンアップの強い候補ケース

依存関係が更新しない

A dependency refuses to update: バージョンを変更したり、ローカルパッケージを再構築したりしましたが、インストールは古いアーティファクトを引き続き取得します。
インストールは、状態を感じさせるように失敗します: 一台のマシンが動作し、もう一台のマシンが動作しない、同じコマンドを実行しても同じ悪い結果が繰り返されるという状況が発生します。
ローカルディスクスペースを取り戻す必要があります: 開発用マシンではこの問題がより重要です。CI環境では短期間しか動作しないため、問題はそれほど深刻ではありません。

他の状況はキャッシュの問題のように見えますが、実際には根本的な原因は別のところにあります。ロックファイルが予期せずに変更された、ワークスペースの設定が不一致になっている、Dockerビルドが間違ったレイヤーを無効にしている場合などは、キャッシュをクリアしても根本的な原因にはなりません。アプリビルドに取り組むチームは、ネイティブツール、JavaScript依存関係、プラグインの更新などを管理しながら、このような状況に遭遇することがよくあります。この文脈では、__CAPGO_KEEP_0__ プロジェクトの依存関係を管理するための実践的な概要は、常に手元に置いておく価値があります。 managing dependencies in Capacitor projects キャッシュをクリアすることの必要性

キャッシュをクリアすることの必要性キャッシュをクリアすることの必要性キャッシュをクリアすることの必要性

キャッシュをクリアすることの必要性

Yarnのキャッシュクリアは、初期反応として毎回のインストール問題に使用しないでください。

古いまたは汚染されたパッケージ状態の証拠がある場合にのみ使用してください。問題がもっとも起こりそうなのは次の場合にスキップしてください。

状況	最初の動き
ロックファイルのずれ	レビュー `yarn.lock` 変更点を確認し、再インストールを一貫して行ってください。
ワークスペース解決の問題	ワークスペース設定とインストール動作を確認してください。
Dockerの再構築の遅さ	レイヤー順序とキャッシュの持続性をレビューしてください。
CIの不一致	確認してみて、実際にどのディレクトリが復元されるか

環境が間違っているときにインストールが間違っているとき、キャッシュをクリアすることは、次の間違ったインストールが遅くなるだけです。

その区別は時間を節約します。キャッシュを魔法のリセットボタンとして扱うことで生じる多くの無駄なデバッグの原因です。

Yarn Classic v1 のキャッシュをクリアする

Yarn Classic は、多くの開発者がすべての Yarn バージョンがどのように動作するかと想像しているように動作します。ユーザーディレクトリ内に グローバルキャッシュ を使用し、共有キャッシュをクリアします。Yarn Classic のドキュメントはそのように説明し、次の yarn cache clean または yarn キャッシュが再構築されることを注釈しています。 yarn install Yarn Classic のキャッシュをクリアする the Yarn Classic cache CLI docs.

キャッシュをクリアすることは、次のインストールが遅くなるだけです。

実行されるコマンドが実際に削除するものは何ですか

Yarn v1の場合、デフォルトのクリーンアップコマンドは簡単です

yarn cache clean

そのコマンドは共有キャッシュを消去しますが、現在のプロジェクトだけではありません。同じマシン上で複数のリポジトリを扱っている場合、それは重要です。次のインストールでどのリポジトリでもパッケージを再度フェッチする必要があるかもしれません。

この共有キャッシュの設計は、Yarn v1がプロジェクト間で混乱を招く可能性がある一因です。グローバルキャッシュ内の古いアーティファクトは、ローカルパッケージ開発が含まれる場合など、異なるリポジトリに影響を与える可能性があります。

Yarn Classicの実用的なシーケンスは通常以下のようになります

最初にクリーンコマンドを実行してください yarn cache clean
ローカルインストールアーティファクトを削除する必要がある場合 node_modules stateがまだ不一致の場合、isが次の候補になります
再インストールからスクラッチ 再度 yarn install 依存グラフが期待どおりに解決されることを確認するには

キャッシュの保存場所を確認する方法

キャップゴーが提供するYarn Classicでは、キャッシュディレクトリを直接検査または削除したい場合のパスを提供します。

yarn cache dir

その場合、問題が解決されない場合、または共有またはコンテナ化された環境でキャッシュディレクトリの所有者を確認する必要がある場合、CLIコマンドが表示されないかもしれません。

古いツールチェーンでローカル設定を予測可能に保つ場合、キャッシュを直接検査することは、2回目の盲目的なクリーンアップコマンドよりも価値があります。 installing Capacitor CLI step by step Yarn Berry v2+のモダンキャッシュ管理

キャップゴーが提供するYarn Berryでは、キャッシュクリーンアップは単に「グローバルストアを消去して再試行」というものではなくなりました。

キャッシュクリーンアップの比較表

キャッシュモデルが変更されました。

現代のYarnでは、キャッシュの動作はプロジェクト自体に強くつながっています。キャッシュのモデルはプロジェクトごとに異なります。

キャッシュの動作はプロジェクトごとに異なります。キャッシュのモデルはプロジェクトごとに異なります。

なぜか古いアドバイスはあなたを誤魔化す。v1でYarnを学んだチームメンバーは、1つのコマンドで全てのグローバルキャッシュをクリアすることを期待するかもしれない。Berryでは、スコープの考え方が必要だ。 スコープ.

モバイルとウェブパイプラインで異なるビルド出力を扱っている場合、同じスコープの考え方はパッケージマネージャー以外でも適用される。ビルドの種類の比較は、環境の仮定がデバッグに漏れ込むことを思い出させる良い例だ。ここでは、コマンドの詳細の前に、簡単な視覚的な説明がある。 Berryで重要なコマンド

現代のYarnドキュメント

キャッシュファイルを削除する

共有キャッシュファイル yarn cache clean を削除する Yarnの現在のキャッシュクリーンコマンドの参照重要なSwitchを公開する the current Yarn cache clean command reference:

yarn cache clean Yarnの共有キャッシュファイルを削除します。
yarn cache clean --mirror プロジェクトのローカルキャッシュではなく、グローバルキャッシュをクリアします。
yarn cache clean --all 両方のグローバルキャッシュファイルとプロジェクトのローカルキャッシュファイルを削除します。

Yarn v1と比べると、より意図的なワークフローを提供します。

目標	コマンド
デフォルトの共有キャッシュスコープをクリーンする	`yarn cache clean`
グローバルミラーキャッシュをターゲットする	`yarn cache clean --mirror`
ローカルとグローバルキャッシュファイルの両方を完全にリセットする	`yarn cache clean --all`

使用 --all 完全に「やり直し」を実行したい場合に最も近い代替手段を使用します。 --mirror グローバルキャッシュ層に問題があることがわかっている場合に、プロジェクト全体を消去したくない場合は使用します。

決定点: Berry では、スコープを間違って選択すると、キャッシュクリーンが “何もしないように”見えることがよくあります。

実際の違いはこれです。Yarn Classic はデフォルトで広範囲にわたっています。Berry はデザイン上明確です。

Yarn キャッシュのベストプラクティス (CI/CD と Docker に関して)

CI/CD の場合、無批判に Yarn キャッシュをクリアすることは通常間違いです。安全なように思えるのは、状態を削除するからですが、実際はパイプラインが高速で再現性のある速度で動作するために依存している状態を削除することになります。

より有用な質問は次のようになっています。 キャッシュするものと、キャッシュを復元するものとは何でしょうか。

CI/CD と Docker ビルドプロセスの Yarn キャッシュワークフローの 4 つのステップの図示。

パイプラインでキャッシュをクリアすることはよく誤りである理由

CircleCI の議論で、実際のプロジェクトで多くのチームが遭遇する失敗パターンが記述されています。キャッシュクリーンでスローインストールが解決されないのは、古いパッケージアーカイブが原因ではない。実際は、キャッシュディレクトリの不一致、キャッシュセット内のパスが欠けていることなど、Fetch と Link の動作、CircleCI の Yarn キャッシングスレッドで説明されていることです node_modules thread CircleCI Yarn caching thread.

CIシステムでは、根本的な原因が隠されている場合、曖昧な症状「インストールが遅い」や「依存関係ステップが不安定である」などが発生することがあります。開発者はキャッシュをクリアし、再実行し、意味のある改善は得られません。

一般的なパイプラインのミスには以下が含まれます。

誤ったディレクトリをキャッシュする: レストアステップは完了しますが、Yarnはレストアされた場所を使用しません。
ワークスペースパスを無視する: ルート依存関係はレストアされますが、ワークスペースのインストールがまだリリンクする必要があります。
Dockerレイヤーを誤った順序でビルドする: ソースcodeコピーが依存関係レイヤーを無効にすると、パッケージのインストールが毎回実行されます。

CIでは、悪い構成によって引き起こされるキャッシュミスは、汚れたキャッシュとよく似ています。

自動環境でモバイルアプリをビルドしている場合、このシナリオではリリースツールも登場します。チームはよくActionsまたはCircleCIを組み合わせて配布と更新システムと組み合わせます。より広いワークフローの中で、オプションはGitHubのCI/CD設定です。 Capgo’s CI/CD setup for Capacitor appsパッケージマネージャーとビルドキャッシュ戦略と並行して実行します。

CIとDockerのより良いアプローチ

キャッシュの無効化は意識的に行うべきです。

CIのための信頼できるパターンは次のようになります。

キャッシュは依存関係の状態に基づいて行う キャッシュキーは yarn.lock と関連するYarnの設定ファイルに紐付けます。
キャッシュを復元する前に 復元されたパスがYarnが使用する環境で使用するパスと一致することを確認する
インストールは一貫して行う 不変の設定では、ロックファイルの正しさを強制するインストールモードを使用する
実際の変更に基づいて無効化する Yarnのバージョン変更、ロックファイルの更新、キャッシュパスの変更はキャッシュを再構築するのに適切な理由です。

dockerの場合、原則は類似しています:

依存関係マニフェストをコピーする: 依存関係のインストール層をアプリケーションソースから分離することができる場合は、分離してください。
イメージビルドで不要なクリーンアップを避ける: ビルド内でキャッシュを削除すると、有用なレイヤー再利用が失われることがよくあります。
ユーザー所有権を明確にする: rootによって作成されたキャッシュディレクトリは、後で非rootランタイムユーザーでインストールが失敗する可能性があります。

短い決定表が役立ちます:

シナリオ	より良いアクション `yarn cache clean`
CIインストールが復元後で遅い	キャッシュパスと復元順序を検証する
ワークスペースの再接続が頻繁に発生しています	関連するワークスペースのインストールアーティファクトをキャッシュする
Dockerの再構築はインストールを再実行します	依存ファイルのレイヤーを再配置する
依存ファイルの変更後、1つの悪いビルド	キャッシュキーの無効化と、クリーンに再構築する

CIでYarnのキャッシュクリアを使用するのは、古いキャッシュコンテンツが実際の問題であることを確認した後のみです。ほとんどの場合、解決策はキャッシュ設計の改善です。

Yarnキャッシュエラーのトラブルシューティング

キャッシュクリーン後に生じるキャッシュのバグは、最も頭を痛めさせます。キャッシュクリーン、再インストール、Yarnが古いパッケージを引き続き取得するのを止めることができません。その時点で、レジストリが間違っているか、ロックファイルが呪われていると仮定するのは、非常に魅力的です。

Yarnの文書化された歴史的な問題は、どれが発生する理由を示しています。開発者は yarn cache clean <package-name> 古いコピーを残すことができました cache/.tmp, これはインストールが古いバージョンを使用し続け、臨時ディレクトリが削除されないか、完全なクリーンアップが実行されるまで続きました。 Yarnの問題について、古いキャッシュアーティファクト .tmp.

ターゲットのクリーンでも古いパッケージが残っている場合

教訓は単純です。 部分的なクリーンは常に十分ではありません。

バージョンの古さを疑うのではなく、広範な汚染を疑る場合に使用する順序は次のようになります。

最初に明らかなチェックから始めます: 期待どおりのパッケージバージョンとソースを確認するようにしてください。
パッケージごとのクリーンに頼るのはあまりよろしくありません: ターゲットのクリーンでも一時的なアーティファクトが残っている可能性があります。
完全なキャッシュの消去に進みます: 古いバージョンが続いている場合、より広範なキャッシュスコープをクリーンアップしてみてください。
手動でテンプキャッシュパスを検査してください: 古いセットアップでは、 cache/.tmp これが欠けている部分になる場合があります。

パッケージが古いアーティファクトに解決される場合、キャッシュファイルは失敗したターゲットクリーン後に最初に調べるべき場所です。

許可と環境の問題がキャッシュ問題と見なされる場合

すべての「キャッシュエラー」はキャッシュ内容の問題ではありません。

Docker、多ユーザーLinuxシステム、またはCIランナーの場合、キャッシュディレクトリがプロセスが実行しているユーザーと異なるユーザーによって所有されている場合、キャッシュをクリアしても問題が解決しない可能性があります。その場合、Yarnを正しいユーザーで実行するか、ディレクトリの所有権を修復するか、再インストールする前に修復する必要があります。

このような問題は、環境間で一貫してインストールが失敗するため、古いキャッシュのように見えることがよくあります。修復はパッケージに関係のないオペレーションです。

よくある質問：Yarn キャッシュをクリアすることについて

キャッシュをクリアすることは安全ですか

はい。通常の開発では、キャッシュされたパッケージアーティファクトを削除するのではなく、ソースコードを削除することではないため、安全な操作です。Yarnは次のインストールで必要なものを再度ダウンロードまたは再構築することができます。

時間のトレードオフは、クリーンキャッシュは次のインストールで通常より多くダウンロードまたは再構築する必要があることを意味します。

どのくらいの頻度で行うべきですか

Only when you have a reason.

Yarn clear cache shouldn’t be routine maintenance on a healthy project. If you put it into every workflow by habit, you’ll slow down local installs and undermine CI caching. Use it when dependencies are stale, installs look corrupted, or you need a deliberate reset during debugging.

Will it affect production builds

Not directly. Clearing your local or CI cache doesn’t change the application code you’ve committed.

What it does change is the environment that prepares the build. If your production pipeline depends on cached install artifacts, clearing them can make builds slower or expose hidden reproducibility problems. That’s useful during troubleshooting, but it’s not something to sprinkle into release scripts without a reason.

What’s the simplest practical rule to follow

Use the smallest cleanup that matches the problem.

For local debugging, start with the cache scope Yarn uses in that project. For CI and Docker, fix cache design before you start wiping caches. And when a package-specific clean doesn’t work, assume temporary artifacts or environment mismatch before assuming Yarn is broken.

If your team ships Capacitor apps and needs a cleaner release pipeline after dependency or build issues, Capgo is one option for delivering JavaScript and asset updates without waiting for store review, while keeping your build and rollout process separate from package-cache troubleshooting.

V1、Berry、CI/CD用Yarnキャッシュクリアのガイド