前言

最近一段职场之路略显波折，由于原公司资不抵债，已拖欠薪资两个多月，在反复考量后，我无奈选择跳槽，开启了新的职场征程，加入了现在的公司。不同于以往长期在 x86 架构环境下进行开发、调试与部署的工作模式，新公司的核心业务软件均运行在 ARM 架构的 Ubuntu 20.04 系统上。这一转变让我一时有些不适，多年在 x86 平台积累的开发习惯、调试技巧以及环境配置经验，在 ARM 架构下大多需要重新摸索、适配与调整。无论是依赖包的安装、编译工具的兼容，还是开发环境的搭建，都遇到了不少此前未曾接触过的问题，也深刻感受到了跨架构开发的差异与挑战。为了帮助自己快速适应新环境，同时也为了给有类似需求（在 x86 架构主机上部署 ARM 架构 Docker 镜像）的开发者提供参考，避免走不必要的弯路，我整理了这份详细指南，记录从环境准备到镜像运行的完整流程。

概述

本教程将带你完成以下任务：

1. 在一台 x86_64 架构的 Ubuntu 24.04 主机上安装 Docker。
2. 配置 QEMU 仿真支持，使 Docker 能够运行 ARM 架构的容器。
3. 拉取并运行官方 Ubuntu 24.04 ARM 镜像。
4. 验证容器架构，并像操作原生 ARM 环境一样使用它。

整个过程模拟了真实的 ARM 硬件环境，非常适合没有树莓派等 ARM 物理设备的开发者进行交叉编译和测试。

---

前置条件

• 一台运行 Ubuntu 24.04 LTS (Noble Numbat) x86_64 的物理机或虚拟机。
• 具有 sudo 权限的用户账户。
• 稳定的网络连接。

---

第一步：在宿主机上安装 Docker

如果你的宿主机尚未安装 Docker，请按以下步骤操作。Ubuntu 24.04 默认使用 apt 的新版本，安装流程略有不同。

1.1 卸载旧版本（如果存在）

打开终端，执行以下命令，移除可能存在的旧版本 Docker 软件包。

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

提示：系统提示未安装这些软件包是正常的，可以忽略。

1.2 设置 Docker 仓库

更新 apt 软件包索引，并安装依赖项以允许 apt 通过 HTTPS 使用仓库。

sudo apt-get update
sudo apt-get install ca-certificates curl

添加 Docker 的官方 GPG 密钥和仓库。Ubuntu 24.04 的密钥管理位于 /etc/apt/keyrings 目录。

# 创建 keyrings 目录并下载 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 添加 Docker 官方仓库到 Apt 源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

1.3 安装 Docker 引擎

再次更新 apt 索引并安装最新版本的 Docker 引擎和 containerd。

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

1.4 验证 Docker 安装

启动 Docker 并设置开机自启，然后运行经典的 hello-world 镜像进行验证。

sudo systemctl start docker
sudo systemctl enable docker
sudo docker run hello-world

如果看到欢迎信息，说明 Docker 安装成功。

为了方便起见，将你的用户添加到 docker 用户组，这样运行 docker 命令时可以不加 sudo。

sudo usermod -aG docker $USER

重要：执行此命令后，需要注销并重新登录才能生效。

---

第二步：安装和配置 QEMU 仿真支持

QEMU 是让 x86 机器能够运行 ARM 指令集的关键，它通过 binfmt_misc 机制实现这一点。

2.1 安装 QEMU 和 binfmt-support 包

在 Ubuntu 24.04 中，安装必要的 QEMU 用户态仿真包和 binfmt 支持包。

sudo apt-get update
sudo apt-get install qemu-user-static binfmt-support

2.2 注册 QEMU 的 binfmt 处理器

使用 Docker 提供的 tonistiigi/binfmt 镜像，它可以自动检测并注册所有支持的 CPU 架构，这是最简单可靠的方法。

docker run --rm --privileged tonistiigi/binfmt:latest --install all

2.3 验证 QEMU 仿真器是否已注册

运行以下两条命令，确认 ARM 相关的解释器已经准备就绪。

# 查看系统中已注册的二进制格式处理器
ls /proc/sys/fs/binfmt_misc/

# 详细检查 ARM 解释器是否启用，应输出 'enabled'
cat /proc/sys/fs/binfmt_misc/qemu-aarch64

---

第三步：拉取并运行 Ubuntu 24.04 ARM 镜像

一切就绪，现在可以拉取 ARM 版本的 Ubuntu 24.04 镜像了。

3.1 拉取 ARM 架构的 Ubuntu 24.04 镜像

使用 --platform 参数明确指定架构为 linux/arm64。注意，这里的标签已经变为 24.04。

docker pull --platform linux/arm64 ubuntu:24.04

3.2 以交互模式运行 ARM 容器

启动一个基于此镜像的容器，并进入其命令行，同时挂载 QEMU 静态二进制文件以确保仿真正常运行（通常由 binfmt_misc 自动处理，但显式指定更保险）。

docker run -it --rm --platform linux/arm64 -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static ubuntu:24.04 /bin/bash

命令解释：

• -it：分配一个交互式终端。
• --rm：容器退出后自动删除。
• --platform linux/arm64：声明该容器以 ARM64 架构运行。
• -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static：将宿主机的 QEMU 仿真器挂载进容器，确保万无一失。
• ubuntu:24.04：我们拉取的 Ubuntu 24.04 镜像名称。
• /bin/bash：要执行的命令，即启动 Bash shell。

执行后，你会发现终端提示符已变为容器内部的 root 用户。

---

第四步：验证容器环境

在容器内部的 shell 中，运行一系列命令，证明你真的身处 ARM Ubuntu 24.04 之中。

4.1 检查系统架构

uname -m

输出应为 aarch64，这表示你的确运行在 64 位 ARM 架构下。

4.2 查看操作系统版本

cat /etc/os-release

输出将清晰显示 Ubuntu 24.04 LTS (Noble Numbat) 及各版本信息。

4.3 尝试运行 ARM 专属命令

更新包列表并安装一个简单的工具（如 file 命令）来检查二进制文件类型。Ubuntu 24.04 的 ARM 镜像使用 ports.ubuntu.com 作为默认源。

apt-get update
apt-get install -y file

之后，你可以用 file /bin/bash 查看文件类型，输出会包含 aarch64。

file /bin/bash

4.4 退出容器

验证完毕后，输入 exit 或按 Ctrl+D 退出容器。由于启动时带了 --rm 参数，该容器会被自动清理。

exit

---

第五步：进阶使用与最佳实践

5.1 性能说明

性能会比原生 ARM 硬件低不少，因为每条 ARM 指令都需经 QEMU 翻译成 x86 指令执行。这不适合生产环境，但足以应对开发、构建和功能测试。

5.2 为 ARM 开发创建专用 Dockerfile

你可以基于这个 Ubuntu 24.04 镜像构建自己的应用，实现交叉编译。示例 Dockerfile.arm 如下：

# 指定基础镜像的平台为 ARM64 架构，基于最新的 Ubuntu 24.04
FROM --platform=linux/arm64 ubuntu:24.04

# 安装 C++ 开发所需的完整工具链和调试工具
RUN apt-get update && apt-get install -y \
    build-essential \
    gcc-aarch64-linux-gnu \
    g++-aarch64-linux-gnu \
    cmake \
    gdb \
    gdbserver \
    clang \
    clangd \
    libstdc++-13-dev \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /workspace

# 使用 VOLUME 声明持久化挂载点，容器销毁后数据不丢失
VOLUME ["/workspace"]

# 复制项目源码到容器
COPY . .

CMD ["/bin/bash"]

构建时使用以下命令：

docker run -it --rm --platform linux/arm64 \
  -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static \
  -v $(pwd):/workspace \
  my-arm-app:ubuntu24

5.3 在多架构镜像仓库中指定正确的 Manifest

官方 ubuntu 仓库是一个多架构清单（manifest list），Docker 会根据你的 --platform 参数或宿主机架构自动拉取对应版本。但如果拉取专用 ARM 镜像（如一些软件维护者仅提供 ARM 版本），则必须显式指定平台。

5.4 清理 QEMU 注册信息（可选）

如果你不再需要 QEMU 仿真，可以取消注册。

docker run --rm --privileged tonistiigi/binfmt:latest --uninstall qemu-aarch64

---

故障排查

问题 1：容器运行报错 exec format error

• 原因：100% 是因为 QEMU 仿真未正确配置，或没有拉取正确的 ARM 镜像。
• 解决步骤：
  1. 确认镜像平台：docker image inspect ubuntu:24.04 | grep Architecture，应输出 "Architecture": "arm64"。
  2. 重新执行所有 QEMU 安装和注册命令。
  3. 尝试更换挂载路径，如 -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static。

问题 2：在容器内执行某些命令出现 illegal instruction 错误

• 原因：通常是因为某些包含的二进制库不是为 ARM 架构编译的，或者在交叉编译时产生了目标主机不兼容的指令。
• 解决：确保你的所有依赖项都来自 ARM 仓库 (ports.ubuntu.com)。容器内的 apt 源已自动配置为 ARM 版本，无需手动修改。

问题 3：apt-get update 在容器内失败

• 原因：可能是网络或 DNS 配置问题。
• 解决：检查宿主机的网络连接，或尝试在 docker run 命令中添加 DNS 参数：--dns 8.8.8.8。