Как собирать образы для разных платформ через buildx
На этой странице
Образ собирается под конкретную архитектуру процессора: linux/amd64 (большинство серверов) или linux/arm64 (Apple Silicon, AWS Graviton). Образ с M-чипа на amd64-сервере падает с exec format error. docker buildx умеет собирать под несколько платформ сразу и публиковать мультиплатформенный образ — манифест-список, из которого каждая машина скачивает свой вариант. Под капотом — эмуляция QEMU или кросс-компиляция с $BUILDPLATFORM и $TARGETPLATFORM.
Вопрос
Как собрать Docker-образ, который работает и на arm64, и на amd64?
Проблема
# на MacBook M3
docker build -t ghcr.io/team/api:1.0.0 .
docker push ghcr.io/team/api:1.0.0
# на сервере x86_64
docker run ghcr.io/team/api:1.0.0
# exec /usr/local/bin/docker-entrypoint.sh: exec format errorОбраз собран под arm64, а сервер — amd64.
Сборка под одну платформу
docker build --platform linux/amd64 -t api:amd64 .На Apple Silicon это работает через эмуляцию QEMU — медленнее, но надёжно.
Мультиплатформенный образ
docker buildx create --name multi --use # builder, поддерживающий несколько платформ
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t ghcr.io/team/api:1.0.0 \
--push .docker buildx imagetools inspect ghcr.io/team/api:1.0.0
# Manifests:
# Platform: linux/amd64
# Platform: linux/arm64Под одним тегом лежат два образа. docker pull на каждой машине выбирает подходящий автоматически — так устроены все официальные образы (node, postgres, nginx).
Ускорение: собирать нативно, а не эмулировать
Эмуляция npm ci с native-модулями может быть в 5–10 раз медленнее. Если шаг не зависит от целевой платформы (например, сборка JavaScript-бандла), его выполняют на платформе сборщика:
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build # JS одинаков для любой архитектуры
FROM node:24-alpine AS runner # здесь уже целевая платформа
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev # native-модули ставятся под целевую архитектуру
COPY --from=build /app/dist ./dist
CMD ["node", "dist/main.js"]| Переменная | Значение |
|---|---|
BUILDPLATFORM | Платформа машины, на которой идёт сборка |
TARGETPLATFORM | Платформа, под которую собирается образ |
TARGETARCH | amd64, arm64 — удобно для скачивания бинарников |
Ещё быстрее — отдельные нативные сборщики для каждой архитектуры (docker buildx create --append с ARM-машиной) или раннеры CI с нужной архитектурой.
В CI
# GitHub Actions
- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
platforms: linux/amd64,linux/arm64
push: true
tags: ghcr.io/team/api:${{ github.sha }}Частые ошибки
- Собирать на Mac и деплоить на
amd64без--platform. - Копировать в образ
node_modulesс хоста — бинарники под macOS не запустятся в Linux. - Запускать тяжёлый
npm ciв эмуляции, когда можно собрать нативно. - Ожидать, что мультиплатформенный образ появится в локальном
docker image lsбез--pushили containerd image store.
Что важно помнить
- Архитектура — свойство образа; несовпадение даёт
exec format error. - Мультиплатформенный тег — это список манифестов, а не один образ.
--platform=$BUILDPLATFORMв сборочном stage ускоряет кросс-сборку.
Мини-шпаргалка
--platform linux/amd64— под одну платформу.buildx build --platform linux/amd64,linux/arm64 --push— под несколько.imagetools inspect— посмотреть варианты.BUILDPLATFORM,TARGETPLATFORM,TARGETARCH.
Документация
Docker: Multi-platform builds, Docker: Builders, Docker: Multi-platform image with GitHub Actions.