実行するのは 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開発者で、次のことをしたい人もいるでしょう。 Macユーザー向けにアプリキャッシュをクリーンアップする そうした開発者は、パッケージマネージャーがストレージの一部に過ぎないことにしばしば気づきます。
Yarn clear cache に頼るべきでないケース
インストール問題が起きるたびに、まず Yarn clear cache に頼るのはやめましょう。
パッケージの状態が古い、または破損している証拠があるときに使いましょう。次のような問題の可能性が高い場合はスキップしてください：
| 状況 | まず試すべきより良い方法 |
|---|---|
| Lockfileの不一致 | 審査 yarn.lock 変更を反映し、一貫した再インストールを行う |
| ワークスペースの解決エラー | ワークスペースの設定とインストール挙動を確認する |
| Dockerビルドの遅延 | レイヤーの順序とキャッシュの永続性を確認する |
| CI環境での不一致 | 実際に復元されているディレクトリを確認する |
環境自体に問題があってインストールが失敗している場合、キャッシュをクリアしても、次の失敗するインストールが遅くなるだけです。
この違いを理解することが時間の節約につながります。キャッシュを「魔法のリセットボタン」のように扱うことで、多くのデバッグ作業が無駄になっています。
Yarn Classic v1 でのキャッシュクリア
Yarn Classicの挙動は、多くの開発者が今でもYarnの全バージョンに当てはまると思っている挙動に近いものです。Yarn Classicは グローバルキャッシュ をユーザーディレクトリ内に置き、 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 削除することとして 共有キャッシュファイル、そして現在の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 インストールが遅い | キャッシュパスとリストア順序を確認する |
| ワークスペースの再リンクが依然として多発する | 関連するワークスペースのインストール成果物をキャッシュする |
| アプリのインストール数 | 依存関係ファイルを基準にレイヤーを並べ替える |
| 依存関係変更後の1回のビルド失敗 | キャッシュキーを無効化し、クリーンに再ビルドする |
CI で Yarn clear cache を使うのは、古いキャッシュの中身が実際の問題だと確認できたときだけにしてください。ほとんどの場合、解決策はキャッシュ設計の改善です。
よくあるYarnキャッシュエラーのトラブルシューティング
最も厄介なキャッシュのバグは、キャッシュをクリアしても解消されないものです。対象を絞ったクリーンアップと再インストールをしても Yarn が古いパッケージを取得し続けるなら、レジストリが間違っているか lockfile が壊れていると疑いたくなります。
Yarn の記録に残る過去の issue が、なぜそうなるのかを示しています。開発者からの報告によると、 yarn cache clean <package-name> 古いコピーを残してしまうことがあり、 cache/.tmpそのため、一時ディレクトリが削除されるか完全なクリーンアップが実行されるまで、インストールは古いバージョンを使い続けていました。これについては、 Yarn の古いキャッシュアーティファクトに関する issue で議論されています。 .tmp.
対象を絞ったクリーンでも古いパッケージが残る場合
教訓はシンプルです。 部分的なクリーンアップだけでは足りないこともあります。
広範囲な破損ではなく、バージョンが古いまま残っている疑いがある場合は、次の順で試してください：
- まずは基本的な確認から： デバッグ対象のパッケージバージョンとソースが正しいか確認します。
- パッケージ単位のクリーンだけを過信しないでください： 対象を絞ったクリーンアップでは、一時的なアーティファクトが残ることがあります。
- キャッシュ全体の削除に進む： 古いバージョンが残り続ける場合は、より広いキャッシュ範囲をクリーンしてください。
- 一時キャッシュのパスを手動で確認： 古い環境では、
cache/.tmpこれが解決の鍵になることがあります。
パッケージが古いアーティファクトに解決され続ける場合、対象を絞ったクリーンが失敗した後は、多くの場合まず一時キャッシュファイルを確認します。
キャッシュの問題に見える権限や環境の問題
すべての「キャッシュエラー」がキャッシュの内容に起因するわけではありません。
Docker、マルチユーザーの Linux システム、または CI ランナーでは、キャッシュディレクトリの所有者が Yarn を実行しているプロセスと異なるために、権限エラーが発生することがあります。その場合、所有権の問題を解決しない限り、キャッシュをクリアしても解決しません。現実的な対処法は、正しいユーザーで Yarn を実行するか、再インストール前にディレクトリの所有権を修正することです。
このような問題は、環境によってインストールが不安定になるため、古いキャッシュが原因であるかのように見えることがよくあります。解決策は運用面での対応であり、パッケージ自体の問題ではありません。
Yarnキャッシュの削除に関するよくある質問
Yarnキャッシュを削除しても安全ですか？
はい。通常の開発において、これは安全な操作です。削除するのはキャッシュされたパッケージのアーティファクトであり、アプリケーションのソースコードではないからです。Yarn は次回のインストール時に必要なものを再度取得できます。
トレードオフは時間です。キャッシュをクリアすると、次回のインストール時に通常よりも多くのダウンロードや再ビルドが必要になる可能性があります。
どのくらいの頻度で行うべきですか？
理由がある場合にのみ行ってください。
プロジェクトが健全な状態であれば、`yarn cache clean` を日常的なメンテナンスとして行うべきではありません。習慣的にすべてのワークフローに組み込んでしまうと、ローカルのインストール速度が低下し、CI のキャッシュも損なってしまいます。依存関係が古くなっている場合、インストールが破損しているように見える場合、またはデバッグ中に意図的なリセットが必要な場合にのみ使用してください。
本番ビルドに影響はありますか？
直接的には変わりません。ローカルまたは CI のキャッシュをクリアしても、コミット済みのアプリケーションの code が変更されることはありません。
影響を受けるのは、ビルドを準備する環境です。プロダクションのパイプラインがキャッシュされたインストール成果物に依存している場合、キャッシュをクリアするとビルドが遅くなったり、再現性の問題が表面化したりすることがあります。これはトラブルシューティングには有用ですが、理由もなくリリーススクリプトに組み込むべきではありません。
実践的で最もシンプルな判断基準は？
問題の規模に合わせた、最小限のクリーンアップを行ってください。
ローカルでのデバッグなら、そのプロジェクトでYarnが使用しているキャッシュスコープから始めましょう。CIやDockerの場合は、キャッシュを削除する前にキャッシュ設計を見直してください。また、特定のパッケージのクリーンアップで解決しない場合は、Yarnの不具合を疑う前に、一時的な成果物や環境の不一致を疑いましょう。
もしチームで Capacitor アプリを配信しており、依存関係やビルドの問題解決後に、よりクリーンなリリースパイプラインが必要なら、 Capgo ストアの審査を待たずにJavaScriptやアセットのアップデートを配信できる選択肢となります。これにより、ビルドやロールアウトのプロセスを、パッケージキャッシュのトラブルシューティングから切り離して管理できます。
