Distrobox 搭建 ROS Melodic 环境

目标：在 Ubuntu 26.04 宿主机上，通过 Distrobox 运行 Ubuntu 18.04 容器，并在容器内安装 ROS Melodic。

核心原则：

所有包管理只用 apt，不使用 rosdep
全部使用华为镜像源加速
不装 Docker，只用 Podman + Distrobox（rootless，更安全）

一、宿主机准备（Ubuntu 26.04）

1.1 确认系统版本

BASH

lsb_release -a
uname -r

预期输出：

Distributor ID: Ubuntu
Description:    Ubuntu 26.04 LTS
Release:        26.04
Codename:       resolute
7.0.0-14-generic

1.2 设置华为 Ubuntu 镜像源

Ubuntu 26.04 使用 deb822 格式，配置文件路径为 /etc/apt/sources.list.d/ubuntu.sources。

BASH

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak.$(date +%Y%m%d)

sudo tee /etc/apt/sources.list.d/ubuntu.sources << 'EOF'
Types: deb
URIs: https://mirrors.huaweicloud.com/repository/ubuntu/
Suites: resolute resolute-updates resolute-backports
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

Types: deb
URIs: https://mirrors.huaweicloud.com/repository/ubuntu/
Suites: resolute-security
Components: main restricted universe multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
EOF

sudo apt update

1.3 安装 Podman + Distrobox

BASH

sudo apt install -y podman distrobox

验证安装：

BASH

podman --version    # podman version 5.7.0
distrobox --version # distrobox: 1.8.2.4

1.4 用户组配置（串口/摄像头权限）

BASH

sudo usermod -aG dialout $USER   # 串口权限
sudo usermod -aG video $USER     # 摄像头/GPU 权限

注意：添加组后需要完全注销并重新登录才能生效。

二、创建 Ubuntu 18.04 容器

2.1 拉取 Ubuntu 18.04 镜像

由于 docker.io 在国内访问不稳定，使用道客云镜像加速：

BASH

podman pull docker.m.daocloud.io/library/ubuntu:18.04
podman tag docker.m.daocloud.io/library/ubuntu:18.04 ubuntu:18.04

验证镜像：

BASH

podman images | grep ubuntu
# 输出示例：
# localhost/ubuntu                     18.04   f9a80a55f492   3 years ago   65.5 MB

2.2 创建 Distrobox 容器

BASH

yes | distrobox create \
  --image ubuntu:18.04 \
  --name ros-melodic-box \
  --home ~/distrobox-homes/ros-melodic

参数说明：

--image ubuntu:18.04：使用本地已打标签的 18.04 镜像
--name ros-melodic-box：容器名称
--home ~/distrobox-homes/ros-melodic：容器家目录映射到宿主机，数据永久保存

2.3 首次进入容器（关键！等待初始化完成）

重要：Distrobox 首次进入时会自动初始化，安装约 216 个基础包（约 77MB），耗时约 3~5 分钟。

BASH

distrobox enter ros-melodic-box

绝对不要在这个过程中：

按 Ctrl+C 中断
在另一个终端杀掉容器内的 apt 进程
重复执行 distrobox enter

初始化完成后，提示符会变成：

[tm-robot@ros-melodic-box ~]$

如果容器异常退出：是因为初始化被中断了。解决方法是删除重建：
BASH
distrobox stop ros-melodic-box
distrobox rm ros-melodic-box
rm -rf ~/distrobox-homes/ros-melodic
# 然后从 2.2 重新开始

三、容器内环境配置

3.1 设置华为 Ubuntu 镜像源

容器内是 Ubuntu 18.04（bionic），使用传统 sources.list 格式。由于基础镜像缺少 CA 证书，先使用 HTTP 源安装证书，再切换到 HTTPS。

BASH

# 先使用 HTTP 源安装 ca-certificates
sudo tee /etc/apt/sources.list << 'EOF'
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-updates main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-backports main restricted universe multiverse
deb http://mirrors.huaweicloud.com/repository/ubuntu/ bionic-security main restricted universe multiverse
EOF

sudo apt update
sudo apt install -y ca-certificates

# 切换到 HTTPS 源
sudo tee /etc/apt/sources.list << 'EOF'
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-updates main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-backports main restricted universe multiverse
deb https://mirrors.huaweicloud.com/repository/ubuntu/ bionic-security main restricted universe multiverse
EOF

sudo apt update

3.2 安装基础工具

BASH

sudo apt install -y \
    curl gnupg2 lsb-release software-properties-common \
    git build-essential \
    python-rosdep python-rosinstall \
    python-rosinstall-generator python-wstool \
    mesa-utils

python-catkin-tools 不在默认源中，通过 pip 安装：

BASH

sudo apt install -y python-pip
sudo pip install catkin_tools

四、安装 ROS Melodic（只用 apt，不用 rosdep）

4.1 添加华为 ROS 镜像源

BASH

sudo tee /etc/apt/sources.list.d/ros-latest.list << 'EOF'
deb https://mirrors.huaweicloud.com/ros/ubuntu/ bionic main
EOF

# 添加 ROS GPG 公钥
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

sudo apt update

4.2 安装 ROS Melodic 完整版

BASH

sudo DEBIAN_FRONTEND=noninteractive apt install -y ros-melodic-desktop-full

安装时间较长（约 500MB 包，取决于网速），请耐心等待。使用华为源速度约 60 kB/s，预计 10~15 分钟。

4.3 修复依赖冲突（已知问题）

安装完成后，可能会出现 python-rospkg / python-rosdistro 旧包与 -modules 新包的文件冲突。

症状：

dpkg: error processing archive .../python-rospkg-modules_1.5.1-1_all.deb (--unpack):
 trying to overwrite '/usr/lib/python2.7/dist-packages/rospkg/__init__.py',
 which is also in package python-rospkg 1.1.4-1

修复命令：

BASH

sudo apt -o Dpkg::Options::=--force-overwrite install -y \
    python-rospkg-modules python-rosdistro-modules python-catkin-pkg-modules

sudo apt --fix-broken install -y

4.4 验证安装

BASH

# 检查 ROS 包状态
dpkg -l | grep ros-melodic-desktop-full

# 预期输出：
# ii  ros-melodic-desktop-full  1.4.1-0bionic.20230620.175308  amd64  ...

五、环境变量配置

将 ROS 环境变量添加到 .bashrc，这样每次进入容器自动加载：

BASH

echo "source /opt/ros/melodic/setup.bash" >> ~/.bashrc

如果你有 catkin 工作空间，也加上：

BASH

# 假设工作空间在 ~/catkin_ws
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc

立即生效：

BASH

source ~/.bashrc

六、创建工作空间（可选）

BASH

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
# 在这里 git clone 你的 ROS 包
cd ~/catkin_ws
catkin_make

七、日常使用

7.1 进入容器

BASH

distrobox enter ros-melodic-box

进入后已经是 Ubuntu 18.04 环境，所有 ROS 命令直接使用。

7.2 运行 ROS

BASH

# 启动 roscore
roscore &

# 运行小乌龟（桌面环境下窗口直接弹出）
rosrun turtlesim turtlesim_node

# 运行 RViz
rosrun rviz rviz

# 运行 Gazebo
rosrun gazebo_ros gazebo

7.3 宿主机直接执行容器内命令

不需要先 enter 再执行，可以一行搞定：

BASH

# 编译工作空间
distrobox enter ros-melodic-box -- bash -c "cd ~/catkin_ws && catkin_make"

# 运行 launch 文件
distrobox enter ros-melodic-box -- roslaunch your_package your.launch

7.4 导出应用到宿主机菜单（可选）

在容器内执行：

BASH

distrobox-export --app rviz
distrobox-export --app rqt
distrobox-export --app gazebo

导出后，宿主机的应用菜单里会出现 “RViz (on ros-melodic-box)"，点击直接运行。

7.5 停止/启动容器

BASH

# 停止
distrobox stop ros-melodic-box

# 启动（distrobox enter 会自动启动已停止的容器）
distrobox enter ros-melodic-box

# 完全删除容器和数据
podman stop ros-melodic-box
podman rm ros-melodic-box
rm -rf ~/distrobox-homes/ros-melodic

八、硬件/外设使用

8.1 串口设备

Distrobox 默认共享 /dev 目录，串口设备直接可见：

BASH

ls /dev/ttyUSB*   # USB 转串口
ls /dev/ttyACM*   # Arduino / 某些激光雷达
stty -F /dev/ttyUSB0   # 测试读写权限

权限说明：

只要宿主机用户已加入 dialout 组（见 1.4），容器内自动拥有串口读写权限
如果权限不足，在宿主机执行 newgrp dialout 或重新登录

8.2 摄像头

BASH

ls /dev/video*    # 摄像头设备直接可见

8.3 特殊设备（RealSense、CAN 等）

宿主机：负责安装内核模块和驱动
容器内：只装 ROS 驱动包（如 ros-melodic-realsense2-camera）
udev 规则放在宿主机 /etc/udev/rules.d/，然后执行 sudo udevadm control --reload-rules

九、常见问题速查

问题	解决
`docker.io` 拉镜像超时	用 `docker.m.daocloud.io/library/ubuntu:18.04` 代替
容器创建后第一次进入就退出	等待初始化完成（~3-5 分钟），不要中断
容器内 `apt update` 报证书错误	先换 HTTP 源安装 `ca-certificates`，再切 HTTPS
`python-rospkg-modules` 文件冲突	`sudo apt -o Dpkg::Options::=--force-overwrite install -y python-rospkg-modules python-rosdistro-modules`
串口 `/dev/ttyUSB0` 权限 denied	宿主机执行 `sudo usermod -aG dialout $USER`，注销重新登录
GUI 窗口不弹出	确认在桌面环境运行，不是纯 SSH；或尝试 `export DISPLAY=:0`
Gazebo 黑屏/闪退	容器内执行 `export LIBGL_ALWAYS_SOFTWARE=1` 强制软渲染测试

十、为什么不用 rosdep？

本教程遵循你的要求，所有依赖只通过 apt 管理，不使用 rosdep。

场景	做法
ROS 基础依赖	`sudo apt install -y ros-melodic-desktop-full`
额外的 ROS 包	`sudo apt install -y ros-melodic-<package-name>`
系统级依赖	`sudo apt install -y <system-package>`
Python 包	`sudo pip install <python-package>`（少数情况）

不适用 rosdep 的场景：

你的项目所有依赖都可以用 apt 安装（ROS 官方包或系统包）
你不需要跨平台构建（rosdep 的主要价值是统一不同发行版的依赖名）

如果未来需要 rosdep：

BASH

sudo apt install -y python-rosdep
sudo rosdep init
rosdep update

十一、数据备份

你的所有代码和配置都在宿主机的 ~/distrobox-homes/ros-melodic/ 下：

BASH

# 查看容器内文件（在宿主机上）
ls ~/distrobox-homes/ros-melodic/

# 备份整个环境
tar czvf ros-melodic-backup.tar.gz ~/distrobox-homes/ros-melodic/

即使容器被删除，~/distrobox-homes/ros-melodic/ 里的数据仍然保留。重建容器时指定同一个 --home 即可恢复。

十二、VS Code / VSCodium 集成开发环境（踩坑记录）

12.1 为什么要把编辑器也放进容器

如果只在宿主机装 VS Code，C/C++ 扩展的 LSP（clangd / cpptools）和 Python 扩展会读取宿主机的头文件和解释器，导致：

C++ 跳转、补全看到的是宿主机的库；
Python 解释器路径对不上；
compile_commands.json 里的路径和宿主机不一致。

正确做法是让 VS Code 自身运行在容器里，这样所有 LSP、终端、调试器都在 Ubuntu 18.04 + ROS Melodic 环境中。

12.2 微软 VS Code + Dev Containers 的坑

Distrobox 本质是一个 Podman/Docker 容器，理论上可以用 Dev Containers 扩展 Attach。但微软 VS Code Server 从某版本开始要求容器内 glibc >= 2.28，而 Ubuntu 18.04 只有 2.27，会直接报错：

TEXT

Warning: Missing GLIBC >= 2.28! from /lib/x86_64-linux-gnu/libc-2.27.so
Error: Missing required dependencies.

所以 微软 VS Code 官方 Dev Containers 方案在老容器上走不通，需要换 VSCodium。

12.3 VSCodium + open-remote-distrobox 方案

安装 VSCodium。
在 VSCodium 扩展市场里安装 open-remote-distrobox。
如果已有容器，不要直接删除，否则系统级安装的软件（如 /opt/ros/melodic）会丢失。--home 只保存家目录里的代码和配置。

正确做法是在原容器上继续用，或者用 podman commit 备份后再重建。如果确实要重建，创建命令如下：

BASH

# 重新创建，指向原来的家目录
distrobox create \
  --image ubuntu:18.04 \
  --name ros-melodic-box \
  --home ~/distrobox-homes/ros-melodic

注意：--home 只保留 ~/distrobox-homes/ros-melodic/ 下的文件。/opt/ros/melodic、/usr/local 等系统目录在删除容器时会一起消失。重建后需要重新安装 ROS。

在 VSCodium 里按 Ctrl+Shift+P → Remote: Connect to Host...，输入：

TEXT

distrobox+ros-melodic-box

等待 VSCodium Server 下载并启动，然后打开 ~/catkin_ws 或你的工作目录。

12.4 关键：替换 VSCodium Server 的 node

第一次连接时，VSCodium 会把 Server 下载到容器内的 ~/.vscodium-server/bin/。Ubuntu 18.04 的 glibc 只有 2.27，而 VSCodium Server 自带的 node 需要 glibc 2.28，直接启动会报错：

TEXT

/home/jiang/.../.vscodium-server/bin/.../node:
/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found

解决办法是用 unofficial-builds.nodejs.org 的 linux-x64-glibc-217 版本替换它：

BASH

# 进入容器
distrobox enter ros-melodic-box

# 找到当前 VSCodium Server 目录
SERVER_DIR="$HOME/.vscodium-server/bin/vscodium-reh-linux-x64-$(ls ~/.vscodium-server/bin | grep vscodium-reh-linux-x64 | head -1 | sed 's/vscodium-reh-linux-x64-//')"

# 下载 glibc-217 版本的 node
cd /tmp
wget https://unofficial-builds.nodejs.org/download/release/v22.21.1/node-v22.21.1-linux-x64-glibc-217.tar.xz
tar -xf node-v22.21.1-linux-x64-glibc-217.tar.xz

# 备份并替换
cp "$SERVER_DIR/node" "$SERVER_DIR/node.bak"
cp node-v22.21.1-linux-x64-glibc-217/bin/node "$SERVER_DIR/node"

# 验证
cd "$SERVER_DIR"
./node --version

注意：版本号 v22.21.1 和 vscodium-reh-linux-x64-xxx 要和你当前 VSCodium 版本对应。

12.5 升级 libstdc++

替换 node 后，VSCodium Server 的 native addon（如 @vscode/spdlog）还会要求较新的 libstdc++。需要升级：

BASH

# 进入容器
distrobox enter ros-melodic-box

# 添加 toolchain PPA
sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
sudo apt update
sudo apt install -y libstdc++6

# 验证是否包含 GLIBCXX_3.4.26+
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX | tail -5

完成后，在 VSCodium 里重新连接 distrobox+ros-melodic-box，Server 就能正常启动了。

12.6 常见错误速查

错误	原因	解决
`failed to launch server in guest distro`，日志里有 `/run/user/1000/.../control.sh not found`	open-remote-distrobox 的控制脚本路径在容器内不可见	检查 Distrobox 是否已默认挂载 `/run/user/1000`；若仍报错，尝试用 `podman inspect` 查看挂载，或给 open-remote-distrobox 提 issue
`Missing GLIBC >= 2.28`	VSCodium Server 自带的 node 需要 glibc 2.28	按 12.4 替换为 glibc-217 版本 node，并按 12.5 升级 libstdc++
删除容器后 ROS 没了	`--home` 不保存 `/opt/ros` 等系统目录	删除前用 `podman commit` 备份镜像，或重建后重新 `apt install ros-melodic-desktop-full`
VSCodium Server 下载失败	容器内访问 GitHub 受阻	容器内配置代理，或手动下载对应版本放到 `~/.vscodium-server/bin/`

12.7 推荐在容器内安装的扩展

连接成功后，在容器内安装：

llvm-vs-code-extensions.vscode-clangd（C++ 补全）
ms-vscode.cpptools（调试）
ms-python.python（Python）
ms-ros-vscode.ros（ROS 语法高亮，如果可用）

这些扩展都会运行在容器内，看到的是 ROS Melodic 的真实环境，C++ LSP 终于不再索引本机库了。

12.8 实际项目编译依赖示例

在容器里编译真实 ROS 包时，可能会缺少一些非 ros-melodic-desktop-full 自带的依赖。根据实际项目经验，可能需要安装：

BASH

sudo apt-get update

# 点云/SLAM 相关
sudo apt-get install -y ros-melodic-octomap-ros
sudo apt-get install -y libsuitesparse-dev
sudo apt-get install -y ros-melodic-apriltag

# 导航/规划相关
sudo apt-get install -y ros-melodic-costmap-2d
sudo apt-get install -y ros-melodic-teb-local-planner

# RealSense 相关
sudo apt-get install -y ros-melodic-librealsense2
sudo apt-get install -y ros-melodic-realsense2-camera
sudo apt-get install -y ros-melodic-realsense2-description

# 系统库
sudo apt-get install -y libpcap-dev
sudo apt-get install -y libpulse-dev
sudo apt-get install -y libvlc-dev

提示：不同项目依赖不同。如果编译报错 Could not find a package configuration file provided by ...，根据提示用 apt search ros-melodic-xxx 或 apt search libxxx-dev 安装对应包即可。

12.9 CMake 4 兼容性处理

容器内源码编译安装的 CMake 4.0+ 对老项目的 cmake_minimum_required 更严格，可能会报错：

TEXT

Compatibility with CMake < 3.5 has been removed from CMake 4.0.

解决办法是设置兼容变量：

BASH

export CMAKE_POLICY_VERSION_MINIMUM=3.5

建议把它写进 ~/.bashrc，这样每次构建自动生效：

BASH

echo 'export CMAKE_POLICY_VERSION_MINIMUM=3.5' >> ~/.bashrc
source ~/.bashrc

一、宿主机准备（Ubuntu 26.04）#

1.1 确认系统版本#

1.2 设置华为 Ubuntu 镜像源#

1.3 安装 Podman + Distrobox#

1.4 用户组配置（串口/摄像头权限）#

二、创建 Ubuntu 18.04 容器#

2.1 拉取 Ubuntu 18.04 镜像#

2.2 创建 Distrobox 容器#

2.3 首次进入容器（关键！等待初始化完成）#

三、容器内环境配置#

3.1 设置华为 Ubuntu 镜像源#

3.2 安装基础工具#

四、安装 ROS Melodic（只用 apt，不用 rosdep）#

4.1 添加华为 ROS 镜像源#

4.2 安装 ROS Melodic 完整版#

4.3 修复依赖冲突（已知问题）#

4.4 验证安装#

五、环境变量配置#

六、创建工作空间（可选）#

七、日常使用#

7.1 进入容器#

7.2 运行 ROS#

7.3 宿主机直接执行容器内命令#

7.4 导出应用到宿主机菜单（可选）#

7.5 停止/启动容器#

八、硬件/外设使用#

8.1 串口设备#

8.2 摄像头#

8.3 特殊设备（RealSense、CAN 等）#

九、常见问题速查#

十、为什么不用 rosdep？#

十一、数据备份#

十二、VS Code / VSCodium 集成开发环境（踩坑记录）#

12.1 为什么要把编辑器也放进容器#

12.2 微软 VS Code + Dev Containers 的坑#

12.3 VSCodium + open-remote-distrobox 方案#

12.4 关键：替换 VSCodium Server 的 node#

12.5 升级 libstdc++#

12.6 常见错误速查#

12.7 推荐在容器内安装的扩展#

12.8 实际项目编译依赖示例#

12.9 CMake 4 兼容性处理#

一、宿主机准备（Ubuntu 26.04）

1.1 确认系统版本

1.2 设置华为 Ubuntu 镜像源

1.3 安装 Podman + Distrobox

1.4 用户组配置（串口/摄像头权限）

二、创建 Ubuntu 18.04 容器

2.1 拉取 Ubuntu 18.04 镜像

2.2 创建 Distrobox 容器

2.3 首次进入容器（关键！等待初始化完成）

三、容器内环境配置

3.1 设置华为 Ubuntu 镜像源

3.2 安装基础工具

四、安装 ROS Melodic（只用 apt，不用 rosdep）

4.1 添加华为 ROS 镜像源

4.2 安装 ROS Melodic 完整版

4.3 修复依赖冲突（已知问题）

4.4 验证安装

五、环境变量配置

六、创建工作空间（可选）

七、日常使用

7.1 进入容器

7.2 运行 ROS

7.3 宿主机直接执行容器内命令

7.4 导出应用到宿主机菜单（可选）

7.5 停止/启动容器

八、硬件/外设使用

8.1 串口设备

8.2 摄像头

8.3 特殊设备（RealSense、CAN 等）

九、常见问题速查

十、为什么不用 rosdep？

十一、数据备份

十二、VS Code / VSCodium 集成开发环境（踩坑记录）

12.1 为什么要把编辑器也放进容器

12.2 微软 VS Code + Dev Containers 的坑

12.3 VSCodium + open-remote-distrobox 方案

12.4 关键：替换 VSCodium Server 的 node

12.5 升级 libstdc++

12.6 常见错误速查

12.7 推荐在容器内安装的扩展

12.8 实际项目编译依赖示例

12.9 CMake 4 兼容性处理