開発現場において、Composerの「`composer install`がやたら遅い」「Dockerコンテナ内やCI/CDの権限周りで謎のエラーを踏む」「知らぬ間にPCのストレージがComposerのキャッシュで圧迫されている」といったボトルネックに直面したことはないだろうか。
多くの開発者は、Composerを単なる「PHPのライブラリインストーラー」としか捉えていない。しかし、その内部構造とグローバル・ローカルの`config`設定の挙動を完全に支配下置くことで、開発マシンのI/O負荷を劇的に軽減し、チーム全体のビルド速度を別次元へと引き上げることが可能になる。
今回は、公式ドキュメントの端っこに追いやられ、ネットの海を彷徨ってもなかなかヒットしない`cache-files-maxsize`と`cache-read-only`という2つの隠れた設定キーを軸に、ローカル開発環境とコンテナ環境を極限までハックするプロの実践知見を伝授する。
—
1. なぜComposerのキャッシュ機構を知る必要があるのか？（内部挙動の真実）
Composerは、リモートのリポジトリ（Packagistなど）からZIPアーカイブをダウンロードする際、デフォルトでローカルマシン（通常は `~/.cache/composer` または `%COMPOSER_HOME%/cache`）にそのバイナリをキャッシュする。
このキャッシュ機構自体は素晴らしいものだが、現代のモダンなPHP開発（大規模なSymfony/Laravelプロジェクトや、マイクロサービス群の乱立）においては、以下の構造的欠陥が顕在化する。
1. 無限肥大化するキャッシュ: 放置すれば数十GBに達し、SSDの容量を圧迫するだけでなく、OSのファイルシステムインデックス（inodeやファイル検索）のパフォーマンスを低下させる。
2. コンテナ・共有環境での権限競合: Docker（非rootユーザー運用）や、開発者間でホームディレクトリを共有するVDI/踏み台サーバー環境において、キャッシュディレクトリへの書き込み権限エラー（Permission Denied）が頻発する。
これらの課題をスマートに解決するのが、今回深掘りする `config` のチューニングである。
—
2. 核心を突く2つの設定：`cache-files-maxsize` と `cache-read-only`
2.1 `cache-files-maxsize`: キャッシュストレージのガバナンス
Composerはデフォルトで、ダウンロードしたZIPファイルのキャッシュサイズに厳密な上限を設けていない。そのため、古いバージョンのパッケージや、めったに使わない巨大な開発用依存パッケージが永遠にディスクを占有し続ける。
`cache-files-maxsize` を用いることで、グローバルまたはプロジェクト単位でキャッシュの最大許容容量を指定し、それを超えた古いキャッシュを自動的にパージ（LRUに近いアルゴリズムで削除）させることができる。
2.2 `cache-read-only`: 読み取り専用キャッシュによる権限問題の完全バイパス
Dockerコンテナ内でのビルドや、CI/CD環境、あるいはチームで共有するNFS領域などにおいて、「Composerはキャッシュから読みたいだけなのに、キャッシュディレクトリに書き込もうとして権限エラーで落ちる」という絶望的な状況を経験した読者も多いだろう。
`cache-read-only` を `true` に設定すると、Composerはキャッシュ領域を「完全に読み取り専用（Read-Only）」として扱うようになる。これにより、書き込み権限の無い環境であっても、既存のキャッシュプールから高速にパッケージをフェッチしつつ、書き込み試行によるエラーを完全に回避できる。
—
3. 実践：環境を最適化する `composer.json` / `config.json` のベストプラクティス
では、これらの設定をどのように実務へ落とし込むべきか。
グローバル（`~/.config/composer/config.json` または `%APPDATA%/composer/config.json`）に設定する方法と、プロジェクトローカル（`composer.json` の `config` ブロック）に記述する方法があるが、チーム開発の標準化とコンテナ環境の最適化の観点から、それぞれのベストプラクティスを提示する。
パターンA: 開発マシンの肥大化を防ぐグローバル設定例
以下のJSONは、個人の開発マシンにおけるComposerの暴走を防ぐためのグローバル設定の模範解答だ。
{
“config”: {
// キャッシュファイルの最大容量を「5GB」に厳格に制限（単位はバイト、K、M、Gが使用可能）
// これにより、SSDの容量圧迫を防ぎ、古いアーカイブを自動クリーンアップさせる
“cache-files-maxsize”: “5G”,
// 同時ダウンロード数の最適化（デフォルトは相対的に保守的だが、高速回線なら増やす価値あり）
“process-timeout”: 300
}
}
パターンB: Docker / CI環境向けプロジェクト設定例
Dockerコンテナのビルドステージや、厳格な権限管理が敷かれたCIサーバーにおいては、`composer.json` の中に直接環境特有の挙動を閉じ込めるか、環境変数でオーバーライドするのが鉄則だ。
{
“name”: “enterprise/core-backend”,
“description”: “高負荷に耐えうるマイクロサービス向けバックエンド”,
“type”: “project”,
“require”: {
“php”: “^8.2”,
“laravel/framework”: “^10.0”
},
“config”: {
// パッケージの厳密なプラットフォーム要件を強制（ホスト依存の差異を排除）
“platform”: {
“php”: “8.2.15”
},
// 自動ディスカバリーの信頼性を担保
“sort-packages”: true,
// 【重要】コンテナ内や権限制限のある環境で書き込みエラーを防ぐため、キャッシュを読み取り専用にする
// ホスト側でビルドしたキャッシュをコンテナにマウントして読み込ませる構成で絶大な効果を発揮する
“cache-read-only”: false
}
}
※注: ローカル開発でホストのキャッシュをマウントするDocker Compose構成をとる場合、コンテナ内からの実行時は環境変数 `COMPOSER_CACHE_READ_ONLY=1` を渡すアプローチが最も柔軟である。
—
4. プロの裏技：環境変数による動的制御とシェル連携
設定ファイルを静的に書き換えるだけでなく、環境変数を通じてこれらの挙動を動的にコントロールするのが、真のDevOpsエンジニアのやり方だ。Composerは、すべての `config` ディレクティブを `COMPOSER_` プレフィックス付きの環境変数で上書きできる仕様を持っている。
例えば、CI/CDパイプラインやDockerビルドのスクリプト（`Dockerfile` や `Makefile`）では、以下のようにコマンドを実行することで、設定ファイルを汚さずに安全なビルドを実現できる。
【Dockerfileの抜粋例】
ルートユーザーでキャッシュを事前生成した後、非rootユーザーに切り替えてビルドする際の鉄板テクニック
1. キャッシュの読み取り専用モードを強制しつつ、高速インストールを実行
RUN export COMPOSER_CACHE_READ_ONLY=1 \
&& export COMPOSER_ALLOW_SUPERUSER=1 \
&& composer install –no-dev –optimize-autoloader –no-interaction
コマンドラインからの直接確認
現在のComposerがどのようなキャッシュ設定を保持し、どこを参照しているかは、以下のコマンドで一発で診断できる。トラブルシューティングの初手として確実に叩き込もう。
現在有効なすべてのComposer設定をツリー構造でDumpする
composer config –global –list
キャッシュディレクトリのパスと現在の容量を実測する
composer global show –platform
—
5. チーム開発の生産性を極限まで高める周辺エコシステム
設定の共有化と合わせて、日々の開発スピードを加速させる「神プラグイン」と「キーボードショートカット的運用」を紹介する。
絶対入れるべき神Composerプラグイン
1. `hirak/prestissimo` (※PHP 7.3以前、またはComposer 2以前の歴史的遺物 – 現代はComposer 2本体が並列ダウンロードを標準内蔵しているため不要)
- 現代の正解: Composer 2の標準機能（Async Downloader） を信じよ。余計なプラグインを入れるよりも、Composer 2へアップデートすることが最大の最適化である。
2. `bamarni/composer-bin-plugin`
- 概要: プロジェクトのルート `composer.json` とは別に、PHPUnitやPHPStan、Psalmといった開発支援ツール（Dev dependencies）専用の独立した依存関係ツリーを分離・管理できる神プラグイン。
- メリット: メインのプロダクトコードの依存関係と、静的解析ツールのバージョンコンフリクトが100%起きなくなるため、チーム全体のメンテナンスコストが激減する。
チーム開発における設定共有化ルール（Git管理の作法）
チームメンバー全員の開発体験を一致させるため、以下のルールをプロジェクトのオンボーディングドキュメントに明記せよ。
- `composer.json` 内の `config` セクション（`platform` やリポジトリ設定など）は Git で厳格にバージョン管理する。
- ただし、個人のマシンのスペックに依存する `cache-files-maxsize` やローカルパスの設定は、グローバル側（`~/.config/composer/config.json`）に逃がすか、環境変数でラップする。これにより、「人によってビルド挙動が違う」という泥沼のバグを防ぐことができる。
—
結び：ツールの限界を超えるのは、アーキテクトの知識だ
Composerは単なるパッケージマネージャーではない。その内部のキャッシュ戦略、ファイルI/Oの挙動、そして環境変数によるインジェクションの仕組みを深く理解すれば、開発環境のストレスは驚くほど消え去る。
今回解説した `cache-files-maxsize` によるディスク肥大化の防止と、`cache-read-only` による権限エラーの根絶は、大規模開発やコンテナネイティブな現場において、確実にチームの時間を創出する武器となるはずだ。
明日からのビルドを、より速く、よりスマートに。ツールの真価を引き出すのは、いつだって我々エンジニアの知見なのだから。