re:re:actable
Урок 083 минуты чтения

Как собирать образы для разных платформ через 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Платформа, под которую собирается образ
TARGETARCHamd64, 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.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам