コンテンツへスキップ

CIでDockerビルドが遅い?原因を特定して解決

最終更新

CI での Docker ビルドが遅くなる原因は、次の5つのいずれかです。ビルドコンテキストが大きすぎる、レイヤーの順序が悪くキャッシュが効かない、キャッシュが実行をまたいで残らない、1つのステージで処理しすぎている、またはマシンのスペックが足りない。まずは計測してください。ほとんどのビルドでは支配的な原因は1つだけで、違う原因を直すと半日を無駄にしかねません。

これは原因を特定するためのガイドです。キャッシュのバックエンドについてはGitHub Actions での Buildx キャッシュを、レイヤーキャッシュの基本についてはCI での Docker レイヤーキャッシュをご覧ください。

手順1: 時間がどこで消費されているかを確認する

各ステップの所要時間が表示されるよう、プレーンな進行出力を使い、BuildKit のタイミング表示を有効にしてください。

docker buildx build --progress=plain -t app:test . 2>&1 | tee build.log

各ステップは#N DONE 12.3sと表示され、キャッシュされたものはCACHEDと表示されます。ログを上から下まで読み、次の3点を確認してください。

  1. load build contextやtransferring contextにかかった時間と、そのサイズ(MB)。
  2. どのステップがCACHEDになっていて、どのステップがそうなるべきなのか。
  3. どの1つのステップが最も長いか。

GitHub Actions の実行では、同じログがビルドステップに出力されます。直前にプッシュしたブランチの実行と、同じコミットの再実行を比べてください。再実行の方が大幅に速ければ、キャッシュは一部の場合にしか効いていません。どちらも遅ければ、キャッシュがまったく機能していません。

手順2: ビルドコンテキストのサイズ

ビルドの最初の行、transferring context: 1.2GBは手がかりになります。.dockerignoreで除外されていない限り、コンテキストディレクトリ内のすべてが最初の命令が実行される前に BuildKit へ送られます。CI では、これにnode_modules、.git、テスト成果物、カバレッジ、ビルド出力が含まれていることがよくあります。

最初の.dockerignoreの例:

.git
node_modules
**/node_modules
dist
build
coverage
*.log
.env*
.github

転送時間以外にも重要な理由があります。COPY . .の命令は、コンテキスト内の任意のファイルが変わると、そのレイヤーを無効化します。大きく雑多なコンテキストでは、コミットのたびにそのレイヤーが再ビルドされ、それ以降のすべてのレイヤーも引きずられます。適切な.dockerignoreがあれば、コミット間でコンテキストは安定します。

送られている内容を確認するには:

docker buildx build --progress=plain . 2>&1 | grep -i "transferring context"

手順3: レイヤーの順序とキャッシュミス

Docker がレイヤーを再利用できるのは、その命令と、それより上のすべてが変わっていない場合だけです。めったに変わらないものを先に、コミットごとに変わるものを後に置いてください。典型的な間違いは次のとおりです。

FROM node:22
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build

ソースの変更はCOPY . .を無効化するため、ビルドのたびにnpm ciが再実行されます。修正方法:

FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

これでnpm ciは、ロックファイルが変わったときだけ再実行されます。どのエコシステムでも考え方は同じです。マニフェストをコピーし、インストールし、そのあとでソースをコピーしてください。

ほかにも、知らないうちにキャッシュを壊すものがあります。

  • 値が変わるARGやENV(コミット SHA やビルド日時)を早い段階に置くと、それより下のすべてがミスになります。最後のステップへ移動してください。
  • 単独のレイヤーにあるRUN apt-get update。古い状態でキャッシュされてしまいます。apt-get update && apt-get install -y ...を1つのRUNにまとめ、同じレイヤー内でリストを削除してください。
  • 固定されていないベースイメージからのCOPY --from。移動するlatestタグはベースレイヤーを変えてしまいます。バージョンやダイジェストを固定してください。

手順4: 新しいランナーにはキャッシュが存在しない

これは CI で最も大きな原因であり、ノート PC では気づきにくい問題です。GitHub がホストするランナーは新規の状態で起動するため、イメージも BuildKit の状態も存在しません。Dockerfile が完璧であっても、すべてのビルドがフルビルドになります。docker/build-push-action で cache-from と cache-to を使い、キャッシュをどこかにエクスポートして、次回の実行でインポートする必要があります。選択肢(GitHub Actions のキャッシュ、レジストリ、ローカルディレクトリ)とそれぞれの制限については、GitHub Actions での Buildx キャッシュで説明しています。

キャッシュのスコープも確認してください。PR のビルドはmainのキャッシュを読みますが、互いのキャッシュは読みません。また、リポジトリの10 GB の上限により古いエントリは削除されます。詳しくはキャッシュの制限をご覧ください。

手順5: マルチステージビルド

マルチステージビルドは2つの点で役立ちます。最終イメージが小さくなることと、BuildKit が独立したステージを並列にビルドし、ターゲットに不要なステージをスキップすることです。

FROM node:22 AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM deps AS build
COPY . .
RUN npm run build

FROM node:22-slim AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
CMD ["node", "dist/server.js"]

テストやリンターが同じ Dockerfile に含まれている場合は、それぞれに独自のステージを与え、別のジョブで--target testを指定してビルドしてください。そうすると、実行用イメージのビルドがそれを待つ必要がありません。

手順6: BuildKit の設定

現在の Docker では BuildKit がデフォルトのビルダーであり、docker/setup-buildx-actionは buildx ビルダーを明示的に設定します。確認すべき点は次のとおりです。

  • キャッシュマウント(RUN --mount=type=cache,target=/root/.npm npm ci)は、ローカルでの繰り返しインストールを高速化しますが、そのマウントはエクスポートされるレイヤーキャッシュではなく、ビルダー上に存在します。新しいランナーでは空の状態から始まります。Buildx キャッシュガイドの該当セクションをご覧ください。
  • マルチプラットフォームビルド。linux/amd64,linux/arm64を amd64 ランナーでビルドすると、QEMU で arm64 をエミュレートするため、何倍も遅くなることがあります。ネイティブの arm ランナーを使うか、ビルドステージで--platform=$BUILDPLATFORMを指定してクロスコンパイルしてください。
  • 大きなレイヤーのプッシュ。exporting to imageとプッシュに時間がかかっている場合は、レイヤーが大きすぎます。不要なビルド成果物のCOPYや、大きなツリーに対するchown -Rを探してください。後者は、すべてのファイルを新しいレイヤーに複製してしまいます。代わりにCOPY --chownを使ってください。
  • ベースイメージの取得が遅い。より小さいベースイメージを使うか、ランナーの近くにあるレジストリのミラーを使ってください。

手順7: マシン

すべてのステップが適切にキャッシュされていても、コールドビルドがまだ長い場合、残りの時間はコンパイルと圧縮に費やされており、どちらも CPU に比例します。GitHub ホストの2コアランナーがデフォルトです。より大きなマシンではコンパイル時間は減りますが、ネットワーク時間は減らないため、これは最後に検討してください。専用のリモート Docker ビルダーを求めるなら、まさにその課題を中心に設計された評価の高い選択肢として Depot があります。詳しくはDepot との比較をご覧ください。compiler.dev では、既存のワークフローを、Docker レイヤーキャッシュが用意された8 vCPU のマシンで実行でき、料金は1分あたり$0.008です。料金とGitHub ホストランナーの代替案をご覧ください。

簡易チェックリスト

  1. .dockerignoreを設定し、コンテキストを約100 MB以下に抑える。
  2. マニフェストをソースより先にコピーしてインストールする
  3. ビルドアクションでcache-fromとcache-toを設定する
  4. 変動する値(SHAや日付)は最後のレイヤーで使う
  5. 独立したステージに分け、テストは専用のターゲットで実行する
  6. エミュレーションではなくネイティブのアーキテクチャでビルドする

よくある質問

ローカルではDockerビルドが速いのに、CIでは遅いのはなぜですか?

お使いのローカル環境には、レイヤーキャッシュとイメージストアが永続的に残っています。新しいCIランナーは、キャッシュをエクスポートしてインポートしない限り、空の状態から始まります。

.dockerignoreはビルドを高速化しますか?

はい、二つの理由があります。転送するデータが減ることと、イメージに影響しないファイルによるキャッシュの無効化が減ることです。

BuildKitはデフォルトで有効ですか?

現在のDockerリリースでは、有効になっています。GitHub Actionsでは、docker/setup-buildx-actionがbuildxビルダーをセットアップします。これは、ほとんどのキャッシュバックエンドで必要です。

コミットごとにビルドすべきですか?

イメージが必要な場合にのみビルドしてください。プルリクエストではプッシュせずにビルドし、マージ時にプッシュします。Dockerの入力に変更がないときはイメージのビルドをスキップするのが、最も速い対策であることがよくあります。pathsフィルターや、影響を受けた部分のみをチェックする方法を使ってください。

Dockerには、GitHub Actionsのキャッシュで十分ですか?

小規模から中規模のイメージであれば、十分です。大規模なイメージでは、共有上限の10 GBが制約になるため、レジストリキャッシュの方が適しています。

compiler.dev でこの Docker ビルドを実行 カード登録不要 · 200 無料分

無料で試す