Skip to content

feat: add multi-platform Docker image support (amd64 + arm64)#135

Open
tianshanghong wants to merge 2 commits into
miantiao-me:mainfrom
tianshanghong:feat/multi-platform-docker
Open

feat: add multi-platform Docker image support (amd64 + arm64)#135
tianshanghong wants to merge 2 commits into
miantiao-me:mainfrom
tianshanghong:feat/multi-platform-docker

Conversation

@tianshanghong
Copy link
Copy Markdown

Summary

This PR adds multi-platform Docker image support for both linux/amd64 and linux/arm64 by configuring QEMU and Docker Buildx in the existing CI workflow.

Problem

The current Docker image is only built for linux/amd64. Users running BroadcastChannel on ARM64 hosts (e.g., Apple Silicon Macs, AWS Graviton, Ampere Altra, Raspberry Pi, Oracle Cloud ARM instances) must rely on QEMU userspace emulation at runtime to translate x86_64 instructions, which:

  • Significantly increases CPU usage and memory overhead
  • Degrades performance (typically 3-5x slower than native)
  • Can cause compatibility issues with some Node.js native modules

Solution

Added three lines to .github/workflows/docker.yml:

  1. docker/setup-qemu-action@v3 — Installs QEMU user-mode emulation for cross-platform builds
  2. docker/setup-buildx-action@v3 — Sets up Docker Buildx, required for multi-platform builds
  3. platforms: linux/amd64,linux/arm64 — Specifies target architectures for docker/build-push-action

No changes to the Dockerfile are required — node:lts-alpine already provides multi-architecture base images.

Impact

  • Existing amd64 users: No change in behavior
  • ARM64 users: Can now pull and run a native image without emulation
  • Image size: Each architecture variant is built independently; the manifest list allows Docker to automatically pull the correct variant
  • CI time: Slightly increased due to the additional ARM64 build (via QEMU emulation in CI), but this only affects build time, not runtime performance

Testing

  • The Dockerfile uses node:lts-alpine as its base image, which officially supports both amd64 and arm64 architectures
  • The build is a standard Node.js/Astro static site — no architecture-specific native dependencies
  • This is a well-established pattern used across the Docker ecosystem (Docker's official multi-platform documentation)

Add QEMU and Docker Buildx setup to the CI workflow to build
multi-architecture Docker images for both linux/amd64 and linux/arm64.

The existing Dockerfile already uses `node:lts-alpine` which natively
supports multiple architectures, so no Dockerfile changes are needed.

This eliminates the need for QEMU userspace emulation at runtime when
running BroadcastChannel on ARM64 hosts (e.g., Apple Silicon, AWS
Graviton, Ampere, Raspberry Pi), improving both performance and
resource usage.
@tianshanghong
Copy link
Copy Markdown
Author

你好!我在 ARM64 服务器上用 Docker 跑 BroadcastChannel,目前镜像只有 amd64,需要 QEMU 模拟运行,系统负载比较高。

这个 PR 只改了 CI workflow(加了 3 行),Dockerfile 不需要动,因为 node:lts-alpine 本身就支持多架构。

已经在 fork 上跑过 CI,构建和推送都没问题:

manifest 验证:

{
  "manifests": [
    {
      "platform": { "architecture": "amd64", "os": "linux" }
    },
    {
      "platform": { "architecture": "arm64", "os": "linux" }
    }
  ]
}

对现有 amd64 用户没有影响,CI 时间大概多 1-2 分钟。

相关 issue:#136

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant