実行した yarn install直後に、更新したはずの依存関係がまだ古いビルドを解決してしまうことがあります。あるいは、ローカルでは問題ないのに、lockfileを少し変更しただけでCIが突然失敗したり、キャッシュを使っているはずなのにDockerの再ビルドが異常に長引いたりすることもあります。
そんな時、多くの人が検索するのは Yarnのキャッシュをクリアする であり、最初に見つけたコマンドをそのまま貼り付けてしまいます。
それで解決する場合もあれば、全く効果がない場合もあります。理由は単純です。Yarnのキャッシュの挙動は、使用しているYarnのバージョンに大きく依存しており、 Yarn Classic v1 と Yarn Berry v2+ では、適切なコマンドもトラブルシューティングの戦略も大きく異なります。
多くのガイドは yarn cache cleanで終わっています。しかし、それは始まりに過ぎません。重要なのはキャッシュのスコープ、プロジェクトがローカルキャッシュを使用しているか共有キャッシュを使用しているか、そしてそもそも問題が本当にキャッシュなのかという点です。CIやDocker環境では、不適切なキャッシュ戦略が古いパッケージアーカイブよりも大きな問題を引き起こすことがよくあります。
目次
- ビルドが失敗する原因はYarn Cacheかもしれません
- Yarn Cacheをクリアすべきタイミングと理由
- Yarn Classic v1でのキャッシュクリア方法
- Yarn Berry v2+ におけるモダンなキャッシュ管理
- CI/CD と Docker における Yarn キャッシュのベストプラクティス
- よくある Yarn キャッシュエラーのトラブルシューティング
- Yarn キャッシュのクリアに関するよくある質問
ビルドが失敗する原因はYarnのキャッシュかも
よくあるパターンがあります。パッケージのバージョンを上げ、最新の変更をプルして、再度installを実行する。コマンドは完了したのに、アプリはまだ古い依存関係が残っているかのような挙動を見せる。そこで誰かが「キャッシュをクリアしてみたら？」と提案してくる。果たしてそれは本当に解決策なのか、それとも単なる迷信なのか、疑問に思うこともあるでしょう。
それは有効な解決策にもなれば、単なる時間の無駄にもなり得ます。
キャッシュの問題は、通常いくつかの予測可能な形で現れます。ローカルパッケージが更新されない、CIで予期しないものがプルされる、lockfileでは一致しているはずなのに新しいブランチがmainブランチと異なる挙動をする、といった具合です。もしパイプライン全体の不安定さに直面しているなら、キャッシュのデバッグだけでなく、こちらのガイドを参考に、より体系的なビルドの見直しを行うのが効果的です。 Capacitor CI/CDパイプラインのビルド失敗を修正する方法.
実践ルール: Yarnのキャッシュクリアは、ルーチン作業ではなく、診断ツールとして扱いましょう。
厄介なのは、Yarnが時間の経過とともにキャッシュモデルを変更してきたことです。古いプロジェクトではキャッシュはグローバルに共有されます。新しいプロジェクトでは、コマンドのフラグによって、キャッシュのクリーンアップがプロジェクト単位、グローバル、あるいはその両方になる可能性があります。そのため、チームメイトから「とりあえずYarnのキャッシュをクリアして」と言われたら、まず最初にこう問いかけるべきです。 どのYarnですか？
キャッシュを正しく解決するには、まず状況を把握することが重要です。ローカル環境かCIランナーか、Yarn v1かBerryか、あるいは共有キャッシュかプロジェクトキャッシュか。これらを特定できれば、単なる「当てずっぽう」ではなく、正確なコマンドを実行できます。
Yarnキャッシュをクリアすべきタイミングと理由
Yarnのキャッシュクリアは、特定の不具合が発生している場合に有効です。古いパッケージアーティファクトの削除、ダウンロード失敗時の復旧、あるいはYarnにゼロから再構築させるために保存済みパッケージを意図的に消去したい場合などに役立ちます。
キャッシュの問題を示唆する症状
以下のようなケースでは、キャッシュが原因である可能性が高いです：
- 依存関係が更新されない： バージョンを変更したりローカルパッケージを再ビルドしたりしたのに、インストール時に古いアーティファクトが取得されてしまう。
- 状態に依存するようなインストールエラー： あるマシンでは動作するが別のマシンでは動作せず、同じコマンドを再実行しても同じエラーが繰り返される。
- ローカルのディスク容量を確保したい： これは、短命なCI環境よりも開発者のローカルマシンにおいてより重要です。
キャッシュの問題に見えても、実際は別の原因であることもあります。ロックファイルが予期せず変更された、ワークスペースの設定が不整合である、あるいはDockerビルドで誤ったレイヤーが無効化されたといった場合、キャッシュのクリアでは根本的な解決になりません。ネイティブツール、JavaScriptの依存関係、プラグインの更新を並行して扱うアプリビルドの現場では、こうした問題によく直面します。そのため、以下の Capacitor プロジェクトにおける依存関係の管理 に関する実用的な概要を、手元に置いておく価値があります。
パッケージのトラブルシューティングではなく、マシン全体のクリーンアップが目的であれば、システムレベルのガイドも役立ちます。Macユーザー向けに アプリのキャッシュをクリーンアップしたい 開発者の多くは、パッケージマネージャーはストレージ容量を占める要素の一部に過ぎないことに気づきます。
Yarn clear cache を使うべきではない場面
あらゆるインストールエラーに対して、安易に Yarn clear cache を実行しないでください。
パッケージの状態が古くなっている、あるいは破損している証拠がある場合にのみ使用しましょう。以下のような問題の場合は、実行を避けてください：
| 状況 | 推奨される最初のアクション |
|---|---|
| Lockfileの不整合 | 変更内容を確認し yarn.lock 一貫した再インストールを行う |
| ワークスペースの解決エラー | 設定とインストール挙動を確認する |
| Dockerビルドの遅延 | レイヤー順序とキャッシュの永続性を確認 |
| CI環境での不一致 | 実際に復元されているディレクトリを確認 |
環境自体に問題があってインストールが失敗している場合、キャッシュをクリアしても次の失敗が遅くなるだけです。
この違いを理解することが時間の節約に繋がります。キャッシュを「魔法のリセットボタン」のように扱うと、デバッグに多くの時間を浪費してしまいます。
Yarn Classic v1 でのキャッシュクリア
Yarn Classicの挙動は、多くの開発者が今でもすべてのYarnバージョンに対して抱いているイメージに近いものです。これは、 グローバルキャッシュを ユーザーディレクトリ内に使用し、 yarn cache clean その共有キャッシュをクリアします。Yarn Classicの公式ドキュメントでもそのように説明されており、次の yarn または yarn install 実行時にキャッシュが再構築される旨も記載されています。このユーザーディレクトリモデルについては、 Yarn Classicのキャッシュ CLI ドキュメントに記載されています。.
このコマンドが実際に削除するもの
Yarn v1の場合、デフォルトのクリーンアップコマンドは非常にシンプルです：
yarn cache clean
このコマンドは現在のプロジェクトだけでなく、共有キャッシュ全体を消去します。同じマシンで複数のリポジトリを扱っている場合、これは重要な点です。いずれかのリポジトリで次にインストールを行う際、パッケージの再取得が必要になる可能性があります。
この共有キャッシュ設計は、Yarn v1においてプロジェクト間で予期せぬ挙動が発生する一因となっています。グローバルキャッシュ内の古いアーティファクトが残り続けることで、特にローカルでのパッケージ開発を行っている際に、他のリポジトリに影響を与えることがあります。
Yarn Classicにおける一般的な手順は以下の通りです：
- まず clean コマンドを実行します：
yarn cache clean - 必要に応じてローカルのインストール済みアーティファクトを削除します：
node_modules状態が依然として不整合な場合は、次にこれを試すのが一般的です。 - 最初から再インストールします： 実行
yarn install再度実行し、依存関係グラフが期待通りに解決されることを確認します。
キャッシュの場所を確認する方法
キャッシュディレクトリを直接確認または削除したい場合、Yarn Classicは以下のパスを返します：
yarn cache dir
CLI コマンドで問題が解決しない場合や、共有環境・コンテナ環境でキャッシュディレクトリの所有ユーザーを確認する必要がある場合に役立ちます。
古いツールチェーンを使用しており、ローカル環境の再現性を維持したい場合は、こちらのガイドを参考にしてください： Capacitor CLI をステップバイステップでインストールする方法 依存関係をクリーンにリセットするのと相性がいいです。
闇雲にクリーンアップコマンドを叩くよりも、手動でキャッシュを確認する方が価値がある場合が多いです。
v1のプロジェクトなら考え方は単純です。共有キャッシュが1つ、広範なクリーンアップコマンドが1つあり、次のinstallで削除したものが再び取り込まれます。
Yarn Berry v2+ におけるモダンなキャッシュ管理
Yarn Berryは状況を一変させました。Yarn v1に慣れている場合、最大の変化はキャッシュのクリーンアップが単なる「グローバルストアの全削除と再試行」ではなくなったことです。Berryはより精密な制御をサポートしており、対象を把握していれば便利です。
Berryによるキャッシュモデルの変化
モダンなYarnでは、キャッシュの挙動がプロジェクト自体とより密接に結びついています。これは、プロジェクトレベルの制御、Plug’n’Play、そして依存関係がマシン全体の単一キャッシュモデルではなくリポジトリと共存できるワークフローといった、Berryの幅広いアプローチに合致しています。
そのため、古いアドバイスは誤解を招くことがあります。v1でYarnを学んだチームメイトは、1つのコマンドですべてをグローバルに一掃することを期待するかもしれません。Berryでは、次のような観点で考える必要があります。 スコープ.
モバイルとWebのパイプラインで異なるビルド出力を扱う場合、このスコープの考え方はパッケージ管理以外にも当てはまります。比較するのは ビルドの種類 環境の前提がデバッグに漏れ出しがちだという、良い気づきになります。
コマンドの詳細に入る前に、簡単なビジュアル解説です：
Berryで押さえるべきコマンド
最新のYarnドキュメントでは yarn cache clean 削除するものとして 共有キャッシュファイルを、さらに2つの重要なスイッチを公開しています 現在のYarn cache cleanコマンドのリファレンス:
yarn cache cleanYarnの共有キャッシュファイルを削除します。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は設計上、明示的な指定が必要です。
CI/CDおよびDockerにおけるYarnキャッシュのベストプラクティス
CI/CDにおいて、安易にYarnのキャッシュをクリアするのは通常避けるべきです。状態をリセットできるため安全に思えますが、実際にはパイプラインの速度や再現性を支えている重要な状態まで削除してしまうことが多いためです。
より重要な問いは、次の通りです。 「具体的に何をキャッシュし、何をリストアしているのか？」
パイプラインでのキャッシュクリアが、なぜしばしば逆効果になるのか
CircleCIの議論では、多くのチームが実プロジェクトで直面する失敗パターンが示されています。ボトルネックが古いパッケージアーカイブではなく、fetchとlinkの挙動、キャッシュディレクトリの不一致、あるいはキャッシュセットに含まれるべき node_modules パスの欠落であったため、キャッシュのクリーンアップを行ってもインストール速度は改善されませんでした。詳細は以下の CircleCIのYarnキャッシュに関するスレッド.
これが重要な理由は、CIシステムが「インストールが遅い」「依存関係のステップが不安定」といった曖昧な症状の背後に、真の原因を隠してしまうことが多いためです。開発者はキャッシュをクリアして再実行しますが、結局目立った改善は見られません。
パイプラインでよくある間違い：
- 誤ったディレクトリをキャッシュしている： リストアステップは完了しているが、Yarnがリストアされた場所を使用していない。
- ワークスペースパスの無視: ルートの依存関係が復元されても、ワークスペースのインストール作業で再リンクが必要になる場合があります。
- Dockerレイヤーのビルド順序の誤り: ソースの code のコピーが依存関係レイヤーを無効化するため、パッケージのインストールが毎回実行されてしまいます。
CIにおいて、設定ミスによるキャッシュミスは、キャッシュの破損と見分けがつきにくいものです。
自動化された環境でモバイルアプリをビルドする場合、リリースツールも重要な役割を果たします。多くのチームは GitHub Actions や CircleCI を、配信・アップデートシステムと組み合わせて運用しています。そのワークフローにおける一つの選択肢が、 Capacitor アプリ向けの Capgo CI/CD セットアップです。これは、パッケージマネージャーやビルドキャッシュの戦略と併せて検討すべきものです。
より優れた CI と Docker のアプローチ
キャッシュの無効化は、感情的ではなく、意図的に行いましょう。
CIにおける信頼性の高いパターンは以下の通りです:
- 依存関係の状態に基づいたキャッシュ: キャッシュキーを以下に紐付けます：
yarn.lockおよび関連するYarn設定ファイル。 - インストール前の復元： 復元されたパスが、その環境でYarnが使用するパスと一致していることを確認してください。
- 一貫したインストール： イミュータブルな環境では、lockfileの整合性を強制するインストールモードを使用してください。
- 実質的な変更時に無効化： Yarnのバージョン変更、lockfileの更新、またはキャッシュパスの変更は、キャッシュを再構築すべきタイミングです。
Dockerの場合も、考え方は同様です：
- まず依存関係のマニフェストをコピー： 可能な限り、依存関係のインストールレイヤーをアプリケーションのソースコードとは別に保持してください。
- イメージビルド時の不要なクリーンアップを避ける： 同一ビルド内でキャッシュを削除すると、有用なレイヤーの再利用ができなくなることがよくあります。
- ユーザー所有権を明確にしましょう： rootによって作成されたキャッシュディレクトリは、非rootの実行ユーザーによる後のインストール失敗を招く可能性があります。
以下の判断基準が役立ちます：
| シナリオ | より良い対策 yarn cache clean |
|---|---|
| 復元後のCIインストールが遅い | キャッシュパスと復元順序を確認する |
| ワークスペースの再リンクが頻発する | 関連するワークスペースのインストール成果物をキャッシュする |
| Dockerの再ビルドでインストールが走る | 依存関係ファイルの周辺でレイヤーの順序を入れ替える |
| 依存関係の変更後にビルドが失敗する | キャッシュキーを無効化し、クリーンに再ビルドする |
CIでの Yarn clear cache は、古いキャッシュが原因だと確信している場合のみにしてください。多くの場合、より良いキャッシュ設計が根本的な解決策になります。
Yarnのキャッシュエラーに関するトラブルシューティング
最も厄介なキャッシュのバグは、キャッシュをクリアしても解消されないものです。特定のクリーンアップを実行して再インストールしても、Yarnが依然として古いパッケージを取得する場合、レジストリが間違っているか、lockfileが壊れているのではないかと疑いたくなります。
Yarnの過去の既知の問題から、その理由が分かります。開発者からは次のような報告がありました： yarn cache clean <package-name> could leave an old copy behind in cache/.tmp、つまりその一時ディレクトリが削除されるか、完全なクリーンアップが実行されるまで、インストール時に古いバージョンが使い続けられてしまうことを意味していました。詳細は以下の通りです。 Yarnのキャッシュの不整合に関する問題について .tmp.
部分的なクリーンアップでも古いパッケージが残る場合
教訓はシンプルです。 部分的なクリーンアップでは不十分なことがあります。
広範囲な破損ではなく、バージョンの不整合が疑われる場合は、以下の順序で試してください：
- まずは、基本的な確認から始めます： デバッグ対象のパッケージバージョンとソースが正しいか確認してください。
- 特定のパッケージのみのクリーンアップを過信しないでください： ターゲットを絞ったクリーンアップでは、一時的なアーティファクトが残ることがあります。
- 次に、キャッシュ全体の完全な削除へ移行します： 古いバージョンが解消されない場合は、より広い範囲のキャッシュをクリアしてください。
- 一時的なキャッシュパスを手動で確認します： 古いセットアップ環境では、
cache/.tmpこれが解決の鍵となる場合があります。
パッケージが古いアーティファクトを解決し続ける場合、特定のクリーンアップが失敗した後は、まず一時的なキャッシュファイルを調査します。
キャッシュの問題に見える、権限や環境の問題
すべての「キャッシュエラー」がキャッシュの内容に起因するわけではありません。
Docker、マルチユーザーのLinuxシステム、またはCIランナーでは、キャッシュディレクトリの所有者がYarnを実行しているプロセスと異なるために、権限エラーが発生することがあります。この場合、所有権の問題を解決しない限り、キャッシュをクリアしても解決しません。現実的な対処法は、正しいユーザーでYarnを実行するか、再インストール前にディレクトリの所有権を修正することです。
このような問題は、環境によってインストールが失敗したり成功したりするため、古いキャッシュが原因であるかのように見えることがよくあります。解決策はパッケージ関連ではなく、運用面（権限設定）にあります。
Yarnのキャッシュクリアに関するよくある質問
Yarnのキャッシュをクリアしても安全ですか？
はい。通常の開発において、これは安全な操作です。削除するのはキャッシュされたパッケージのアーティファクトであり、アプリケーションのソースコードではないからです。Yarnは次回のインストール時に必要なものを再度取得できます。
トレードオフは「時間」です。キャッシュをクリアすると、次回のインストール時に通常よりも多くのダウンロードやビルドが必要になる場合があります。
どのくらいの頻度で行うべきですか？
理由がある時だけで十分です。
プロジェクトが正常に動作している場合、yarn clear cacheをルーチン作業として行う必要はありません。習慣的にすべてのワークフローに組み込んでしまうと、ローカルのインストール速度が低下し、CIのキャッシュのメリットも損なってしまいます。依存関係が古くなっている、インストールが破損しているように見える、あるいはデバッグ中に意図的なリセットが必要な場合にのみ使用してください。
本番環境のビルドに影響しますか？
直接的な影響はありません。ローカルやCIのキャッシュをクリアしても、コミット済みのアプリケーション code が変更されることはありません。
影響を受けるのは、ビルドを準備する環境です。プロダクションのパイプラインがキャッシュされたインストール成果物に依存している場合、キャッシュをクリアするとビルドが遅くなったり、再現性の問題が表面化したりすることがあります。これはトラブルシューティングには有用ですが、理由もなくリリーススクリプトに組み込むべきではありません。
守るべき最もシンプルで実践的なルール
問題に合わせた最小限のクリーンアップを行う。
ローカルでのデバッグなら、そのプロジェクトでYarnが使用しているキャッシュスコープから始めましょう。CIやDockerの場合は、キャッシュを削除し始める前にキャッシュ設計を見直してください。また、特定のパッケージのクリーンアップで解決しない場合は、Yarnの不具合を疑う前に、一時的なアーティファクトや環境の不一致を疑いましょう。
チームで Capacitor アプリをリリースしており、依存関係やビルドの問題解決後に、よりクリーンなリリースパイプラインが必要な場合、 Capgo は、ビルドやロールアウトのプロセスをパッケージキャッシュのトラブルシューティングから切り離しつつ、ストアの審査を待たずにJavaScriptやアセットのアップデートを配信するための有効な選択肢となります。
