DockerでMac環境のみビルドが止まる原因とメモリ設定の落とし穴

2025.08.17

Docker を日常的に利用していると、Linux サーバでは問題なく動作していたコンテナが、なぜか macOS 環境でだけビルドが停止する、あるいは 極端に遅くなる といった現象に遭遇することがあります。特に M1/M2 Mac など Apple Silicon 世代 では、従来の Intel ベース環境とは挙動が異なることが多く、トラブルシュートに時間を取られることも少なくありません。

本記事は、筆者が遭遇した 「Mac 環境でのみ発生する Docker ビルド停止問題」 と 「メモリ設定の落とし穴」 について、技術者の備忘録としてまとめます。端末依存のパフォーマンス問題に悩む方の参考になれば幸いです。

目次

1. Mac 環境特有の Docker 動作

Docker は Linux カーネル機能を前提としているため、macOS 上では仮想マシン（HyperKit または Apple Virtualization Framework）を介して Linux を動作 させ、その上でコンテナを稼働させています。

📌 ポイント図解

macOS ホスト
   └── Linux VM (HyperKit/Apple Virtualization)
         └── Docker コンテナ群

つまり macOS 上の Docker は、単純に「Linux の上にコンテナ」ではなく、「Linux VM の上にコンテナ」 という二重構造です。このため、CPU アーキテクチャやメモリ割り当てといったホスト依存の挙動が強く影響 します。

Linux サーバで快適に動いていたイメージが Mac 上で急に遅くなるのは、この仮想化レイヤーによる オーバーヘッド や リソース制約 が原因であることが多いです。特に CI/CD 環境とローカル Mac 環境の差異を無視すると、再現困難な問題 に直面します。

2. ビルド停止現象の具体例

筆者が遭遇したのは、Node.js ベースのフロントエンドアプリ を Docker 上でビルドする際のことです。

Linux サーバでは問題なく npm install が完了するのに、macOS 環境では途中で固まったように進まなくなる現象 が発生しました。CPU 使用率は低いまま、I/O 待ち状態に入り、最終的にはタイムアウトすることもあります。

以下のようなシンプルな Dockerfile を利用していました。

FROM node:18
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["npm", "run", "build"]

Linux 上ではスムーズに進むのに、macOS では npm install の途中で停止。原因を調査すると、Docker Desktop のデフォルトメモリ不足 により、内部で OOM（Out of Memory）が発生していたことが判明しました。ログには明示的に OOM が表示されないため、非常に気付きにくいのが落とし穴 です。

📌 図解：挙動の違い

Linux サーバ:  npm install → 正常完了
Mac (2GBメモリ): npm install → 停止 / OOM

3. メモリ設定の落とし穴

Docker Desktop for Mac のデフォルトメモリは約 2GB に制限されています。モダンなフロントエンドや機械学習系のイメージは簡単に 4GB 以上のメモリを消費するため、メモリ不足でビルドが停止するのは自然な結果です。

一方で、Linux サーバ環境ではホストメモリをほぼそのまま利用できるため、同じ Dockerfile でも挙動が異なります。つまり「コードや依存関係に問題はないが、ホスト側の制約で止まる」という現象が発生します。

📌 メモリ利用イメージ

Linux サーバ     : 利用可能 16GB → 正常
Mac (初期設定)   : 利用可能 2GB  → OOM
Mac (設定変更後) : 利用可能 8GB  → 正常

Mac の場合は Docker Desktop の GUI 設定 からメモリを 4GB、8GB など十分に割り当てる必要があります。この差異を知らずに「なぜ Mac だけビルドが止まるのか」と数時間浪費する事例は少なくありません。

4. 実際の対処方法

筆者の環境では、以下の対応で改善しました。

  1. Docker Desktop の Preferences → Resources → Advanced からメモリを 6GB に増加
  2. スワップを有効化 してディスクを補助的に利用
  3. 不要なキャッシュを削除 してピークメモリを低減

さらに docker build に --memory オプションを付与することで、コンテナごとのメモリ制限を明示的に制御 できます。

docker build --memory=4g -t my-app .

ただし Mac 環境ではホスト全体の VM に割り当てるメモリが根本的な制約になるため、リソースを大量に消費するビルドは CI/CD 環境へオフロード する方が合理的です。開発端末で無理に対応するよりも、役割分担を明確化する戦略 が効率的です。

5. 再現性の検証とチーム共有

技術者として重要なのは、問題が端末依存であることをチーム全体に共有し、再現条件を明確化すること です。

  • Linux 環境では発生しない
  • Intel Mac では軽微だが M1/M2 では深刻

といった条件を具体的に記録しておくことが有効です。特に Apple Silicon 環境では x86 イメージをエミュレーション実行 するため、追加のパフォーマンス劣化が発生します。

💡 Tips:

  • --platform=linux/arm64 を利用して ネイティブビルドを実行
  • 環境条件を README や Wiki に明記

端末依存の問題は「誰の環境でのみ起きるのか」を明示しないと、属人的なトラブルシュートに終始します。ドキュメント化とナレッジ共有 が不可欠です。

6. まとめ

本記事では、Docker を利用する際に Mac 環境特有の事情からビルドが停止してしまう問題 と、メモリ設定に潜む落とし穴 について解説しました。

  • Linux サーバでは発生しないが Mac では問題が顕在化する背景 → 仮想化レイヤーとリソース制限
  • Docker Desktop のデフォルトメモリは不足 → GUI 設定やコマンドラインで調整必須
  • Apple Silicon では アーキテクチャ差異による追加課題 にも注意

最終的には、ローカル端末での無理なビルドではなく CI/CD にオフロードする戦略 が推奨されます。端末依存のパフォーマンス問題は避けられませんが、原因を理解し設定を適切に行うことで解消可能 です。

参考

タイトルとURLをコピーしました