Docker で「platform (linux/amd64) does not match」警告が出てイメージを使えない

要約

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) は、Apple Silicon ホストで amd64 のみのイメージを実行した状態。
エミュレーション動作はするが極端に遅く、native 実行できないバイナリで落ちることもある。--platform の明示、buildx マルチアーキ、Rosetta 有効化のいずれかで解消する。

よくある原因

1. amd64 only のイメージ: 公式以外のイメージは arm64 タグを公開していないものがある。
2. FROM 行のミス: FROM node:20-bullseye 等で arm64 が無いタグを指定している。
3. Rosetta 無効: Docker Desktop 4.16 以降で利用できる x86_64 emulator が無効のままで、QEMU 経由の遅いエミュレーションになっている。
4. CI とホストの差: GitHub Actions の ubuntu-latest は amd64、ローカル Mac は arm64 で、build 物のキャッシュが食い違う。

解決策

1. プラットフォームを明示

docker run --platform=linux/arm64 myimage:tag
docker pull --platform=linux/amd64 myimage:tag

公開側で arm64 タグが用意されていれば、明示するだけで native 実行に切り替わる。

2. buildx でマルチアーキビルド

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/me/app:latest --push .

公式の Multi-platform images ドキュメント のとおり、buildx で一度のコマンドで複数アーキの manifest list が作れる。
配布側で揃えれば利用側で警告は出なくなる。

3. Rosetta を有効化

Docker Desktop の Settings → General → Use Rosetta for x86_64/amd64 emulation on Apple Silicon を有効にする（Docker Desktop の Mac 設定ドキュメント）。
QEMU より高速で、amd64 only のイメージしか使えない場面で体感差が大きい。

4. Dockerfile を両対応にする

FROM --platform=$BUILDPLATFORM node:20 AS build
ARG TARGETPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

$BUILDPLATFORM と $TARGETPLATFORM を使い分けると、ビルド側でクロスコンパイルしつつ、実行イメージは target に揃えられる。